4.6 KiB
AGENTS.md
Codex / AI coding agent 的仓库级入口。进入本仓库后，先读本文，再进入
docs/00-ai-start-here.md。
项目定位
本仓库是 harness coding 文档样本库，用来沉淀一个新项目交给 AI coding agent 开发前应准备的文档集合。
当前不是业务应用代码仓库，而是文档模板仓库。默认任务是维护、改进、补充这些模板，让它们更适合复制到新项目中使用。
文档位置
harness coding 需要的项目文档模板主要集中在 docs/ 目录；根目录还包含 progress.md 执行流水模板。
后续 Codex 或其他 AI coding agent 进入使用这些模板的新项目时，应先读取仓库级规则文件，再从 docs/00-ai-start-here.md 和 docs/agent-context.json 建立上下文；入口文件负责流程，清单负责把任务类型路由到需求、技术栈、架构、编码规则、任务文件和当前状态。
根目录 README.md 和 docs/README.md 主要用于人类快速了解样本库和文档清单；agent 真正开始编程时，以 docs/00-ai-start-here.md 作为工作入口。
必读顺序
维护本样本库时，每次开始工作前仍按顺序完整读取：
README.md：了解本仓库用途和文档集合。docs/README.md：了解文档导航。docs/00-ai-start-here.md：理解新项目中 agent 的入口流程。docs/05-coding-rules.md：理解模板中的编码纪律。progress.md：理解执行流水和当前状态的职责边界。- 与当前任务相关的具体文档。
模板复制到业务项目后，日常会话可按最小路径读取：
- 仓库级规则和
docs/agent-context.json。 - 清单
bootstrap.always_read中的文件。 - 本轮任务文件或对应 Gitea Issue。
- 清单中与任务类型匹配的
routes；重复路径只读一次。
领取任务时记录默认分支头提交为 context_ref；同一会话中文件 SHA 未变化时可复用已读内容，ref 变化后重新读取清单和受影响文档。
模板复制到启用 Gitea 协作的项目后，还应先读 docs/gitea-collaboration.md：dispatcher 串行检查写路径和分配任务，每个任务以唯一 claim 分支防重复领取；每个 worker 同时最多一个活跃任务，工作分支 / worktree 独立，活跃任务的 write_paths 不得重叠。
任务内评审采用风险分级的单写者模型：
review_mode: none：低风险文档、链接或非敏感简单配置，只要求唯一写入 Agent 和自动验证。review_mode: test：普通行为变更，增加一个只读测试评审 Agent。review_mode: dual：权限、Token、隐私、数据迁移、公共 API / Schema、核心架构、部署或外部平台集成，增加只读测试评审 Agent 和只读安全/架构评审 Agent。- 只有写入 Agent 持有
claimed_by、工作分支和仓库写权限；评审 Agent 不修改文件、不提交 Git、不更新 Gitea，也不在共享工作区执行有副作用的命令。 - 评审必须针对固定候选提交 SHA；修复产生新 SHA 后重新评审。dispatcher 汇总
ACCEPT/REVISE/BLOCK，存在未解决的阻断或高风险问题时不得合并。
如果用户要求修改某类模板，优先阅读对应文件，不要只凭文件名猜内容。
工作规则
- 保持这些文件是“可复制到新项目”的模板，不要写入只适用于当前机器的业务事实。
- 可以引用
D:\opc_project\lingo\docs作为参考来源，但不要把 lingo 的具体业务内容照搬进通用模板。 - 文档中使用
【占位符】表示新项目需要替换的内容。 - 修改导航时，必须同步检查
README.md和docs/README.md的链接。 - 新增文档时，必须在根目录
README.md和docs/README.md中登记。 - 不要删除已有模板，除非用户明确要求。
风格
- 文档默认使用中文。
- 标题、表格、任务状态、文件名保持简洁稳定。
- 内容要面向 agent 执行，而不是泛泛讲原则。
- 每条规则最好能落到“读取什么、修改什么、验证什么”。
验证
本仓库目前是纯文档仓库。修改后至少检查：
Get-ChildItem -Recurse -File
如修改链接或文件名，使用 rg 搜索旧名称和新名称，确认引用一致。
涉及上下文清单、任务协议或 Gitea 模板时，再运行：
python -m unittest discover -s tests -p "test_*.py"
python scripts/validate_harness_governance.py
远端协调审计是可选只读检查，需要本机私有 Gitea 配置：python scripts/audit_gitea_coordination.py --repo 【owner/repo】 --dispatcher 【Gitea登录名】。