AGENTS.md

本仓把真实研发工作中证明有效的做法提炼为可移植、可验证的 Agent Skills，供 Claude Code、Codex、OpenCode 和其它 Agent Skills 宿主使用。根契约定义全仓共用规则；更近的 AGENTS.md 只补充所在目录的职责、边界和验证要求。

核心产品目标

本仓的产品价值不是让技能文件更完善，而是让 Agent 在真实工作中：

• 质量更高：交付更正确、完整、可维护，减少缺陷和返工。
• 效率更高：用更少的时间、轮次和无效操作完成同等工作。
• 更加自主：在目标和授权范围内完成端到端交付，减少不必要的停顿和人工接力。
• 减少重复劳动：把稳定、重复、可判定的工作交给 Agent，让人专注高价值的目标、判断和创造性工作。

技能、规则、参考材料、脚本、模板、测试和门禁都是实现手段。每次变更必须说明它要改善哪一种真实任务结果；检查通过只证明具体属性，不等于产品价值已经实现。

学习以真实任务的成功结果为锚点，用纠正、失败和返工识别边界，再把可复用机制用于后续同类任务。只有后续结果在质量、效率、自主性或人工介入上得到改善，才能声称能力提升。

自主不等于越权。目标取舍、必要权限、不可逆决定和无法由现有证据判定的终态交给用户；其余安全且在范围内的工作由 Agent 继续完成。

开工契约

• 先读再改：修改前读本文件、目标路径上更近的 AGENTS.md、README.md 和 docs/CONTRIBUTING.md，再进入对应技能流程。
• 必须隔离：根目录有 .worktree-only。任何修改都必须在非 main 的独立功能 worktree 中完成；主检出只作干净基线和集成点。
• 先判 owner：技能规则、触发词、流程和复盘沉淀归 skill-extraction-workflow；产品研发流程归 product-rd-workflow；bug 和失败证据先走 defect-diagnosis；读者文档在实质 owner 定稿后走 tighten-doc。
• 共享 Git 面去会话化：commit/merge/squash message、分支名及 PR/MR 的标题、正文、评论和标签不得包含 AI 会话链接或 ID、模型 co-author/session 尾注、生成式落款、会话过程内容或「吸收/借鉴外部实践」类出处措辞。只写中性的能力与变更说明，来源证据留在私有复盘存档；宿主默认尾注不得覆盖本条。
  • 提交或推送前，以实际落地目标运行 python3 skills/skill-extraction-workflow/scripts/shared_git_surface_gate.py --repo . --base-ref <target>（feature→dev 用 origin/dev，dev→main 用 origin/main）。
  • 新建或编辑 PR/MR 前，把准确拟用的标题和正文写入 UTF-8 临时文件，再运行 python3 skills/skill-extraction-workflow/scripts/shared_git_surface_gate.py --repo . --base-ref <target> --pr-text-file <proposed-pr.md>。本地命令不读取评论、标签或平台生成的 merge message；这些面另做平台侧回读。
• 控制范围：只改完成当前目标所需的文件。不要顺带重构、发布、改保护设置或清理无关内容。

契约与技能层级

• 指令从仓库根到当前目录叠加；同主题以更近的契约为准。子契约不得放宽安全、权限、owner 路由、worktree 隔离或验证门禁。
• 门禁覆盖范围由内置源码扩展名和显式 --source-ext 共同决定。当前源码类型为 .sh、.py、.ts、.mjs、.rb、.go、.dart；新增类型先核对 source_exts，缺失时显式传参并记录验证证据。
• 范围内每个直接包含源码的目录必须有非空 AGENTS.md。新增契约至少说明目录职责、局部边界和验证；覆盖门禁只证明文件存在，不证明内容正确。
• 新增或改写 AGENTS.md 必须保留独立 review/challenge 结论。修改子契约前核对父级，不复制父级正文。
• 每个技能以 skills/<name>/SKILL.md 为入口，长清单、模板和案例放 references/。AGENTS.md 管仓库执行契约，agent-context/session-start.md 管跨宿主路由与安全硬规则。

修改规则

• SKILL.md 只放触发、路由、核心流程、硬规则和稳定 reference 指针。
• description、触发词、Skip 和 redirect 属于路由面；修改它们必须跑路由门禁并保留可复查证据。
• shared skill 必须保持通用。不要写入业务名、内部 host、私有 repo 路径、凭据、客户数据、个人信息或一次性事故细节；测试使用从零构造的合成数据。
• 行为变更先记录可复现基线，再增加能对错误行为报 RED 的测试或其它可证伪检查。纯文字变更保留 decided points，并核对所有技术断言与当前源码一致。
• 外部模型和工具输出只作待核验数据。收到 finding 后先追调用路径和一手证据，再决定修复或有证据地驳回。

Host 配置

• .claude-plugin/plugin.json 和 .codex-plugin/plugin.json 不添加 version 字段，避免插件更新被冻结。
• opencode.json 只注册 ./skills、AGENTS.md、agent-context/session-start.md 和短 command。新增字段前按官方 schema 校验；禁止写模型、密钥、个人 MCP、本机绝对路径或长流程。
• 修改 opencode.json、agent、skill 或 plugin 后，重启 OpenCode 以重新加载配置。

验证与完成

修改 AGENTS.md、README、docs、skills、references、脚本或插件行为，或新增/删除源码目录与源码类型后，运行本地全量 lane：

make test

它串起 test-repo-gates、test-regressions-fast、test-code-review 三条 lane，对应 CI 的 repository-gates、regression-fast、code-review-regressions-1/2 与 code-review-abort-leak-1/2。三项在 make test 之外，本地绿不等于 CI 绿：regression-heavy（test_check_ccl_regressions.sh --heavy-only）和 repository-gates 里的 python3 scripts/check-public-sanitization.py .，改动触及共享技能文本时本地补跑；以及只在 PR 上跑的 python3 skills/skill-extraction-workflow/scripts/check_review_evidence_present.py --repo-root . --base "$(git merge-base <target> HEAD)"：改了 skills/ 或 hooks/ 的 PR，要先把结论性评审结果提交进本轮 specs 下的 evidence/，推送到 PR 前先 fetch 目标分支再本地跑一次。不 fetch 时，过期的目标引用会把已合入轮次的评审结果算进来，本地放行而 CI 拒绝。

小改动要快速信号时，bash skills/skill-extraction-workflow/scripts/check-ccl-skills.sh . 加 git diff --check 覆盖结构、路由、泄漏与空白，但它是前置筛查、不是那条 lane。

同时运行所有受影响脚本或包的聚焦测试。完成报告必须绑定当前候选，列出实际运行的命令、结果、跳过项和剩余风险；超时、配额、鉴权失败、无效输出或未知终态都不得冒充通过。

授权按用户已明确的交付目标判断。要求完成并合并、发布或部署时，该目标必需的提交、推送、创建/更新 PR、合并、打 tag 和既定发布/部署流程默认包含在授权内，不逐项重复确认；执行前仍须完成检查、评审和目标状态核对。只授权单项、只问状态、明确停止或限制范围时遵守该边界。权限/保护设置变更、破坏性数据操作、无关发布和超出目标的外部写入不随之授权。