ccl-skills AGENTS.md

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 管跨宿主路由与安全硬规则。