<项目名> Agent 协作协议（项目覆盖层）

本项目基于 ACK Skill v<ack_version>。通用规范由 /ack 从 Skill 自身的 references/ 读取；本文件只保存项目差异。

本文件是「项目覆盖层」，文件名可配置。 默认放 docs/ack/project.md，不占用 AGENTS.md，避免与团队已有的 AGENTS.md 约定冲突。若希望 Agent 自动加载，可由项目维护者自行在 AGENTS.md 中引用本文件；ACK 不会自动修改 AGENTS.md、CLAUDE.md 或其它 Agent 指令文件。无论叫什么，都在 tasks.yaml 的 project.overlayFile 记录实际路径。 docs/ack/ 只保存本项目的 project.md、tasks.yaml 与 knowledge.yaml，不复制或链接 Skill。

项目概览

项目：<project_name>
技术栈：<tech_stack>
运行命令：<run_command>
Base URL：<base_url>
任务板：docs/ack/tasks.yaml
项目知识：docs/ack/knowledge.yaml
覆盖层文件：<overlay_file_path>（默认 docs/ack/project.md）

通用规范（由 ACK Skill 按需读取）

开始需求：references/kickoff.md
角色、权限、状态机与完成定义：references/roles-and-permissions.md
模型档位与升级规则：references/model-routing.md
闭环流程与 worktree 对齐：references/closed-loop.md
验收信号与三轮策略：references/optimization-method.md
派发 prompt 模板：references/prompt-templates.md
Orca 编排命令（可选）：references/orca-adapter.md

模型档位（项目可覆盖，默认见 references/model-routing.md）

角色	默认档位	本项目实际
Coordinator (PM)	强模型	`<model_or_default>`
Test	中低模型	`<model_or_default>`
Developer	中低模型	`<model_or_default>`

路径权限（项目覆盖层，必须填实际路径）

路径	Coordinator	Test	Developer	说明
`<spec_paths>`	R/W	Read-only	Read-only	产品规格、API 文档、计划（PM 拥有）
`<integration_test_paths>`	Read-only	R/W	Read-only	浏览器/API 回归（Test 拥有）
`<test_records_path>`	Read-only	R/W	Read-only	复测记录
`<source_paths>`	Read-only	Read-only	R/W	应用源码
`<unit_test_paths>`	Read-only	Read-only	R/W	单元测试
`<shared_config_templates>`	Read-only	Read-only	R/W	可提交配置模板
`<local_config_paths>`	Read-only	Read-only	Read-only	本地私有配置
`tasks.yaml`	R/W	Read-only	Read-only	只有 Coordinator 写
`knowledge.yaml`	R/W	Read-only	Read-only	只有 Coordinator 写；Developer/Test 通过回报提名或验证

命令（项目覆盖层）

Developer 白盒验证：

<unit_test_command>
<build_command>
<local_run_command>

Test 黑盒复测：

<preflight_command>
<api_smoke_command>
<browser_regression_command>

知识项的 verification.ref 只能引用 knowledge.yaml.verificationRegistry 中已审查的检查入口。Registry 只保存仓库内相对 path 和结构化 args，不保存或执行自由 shell 命令；新项目没有知识时保持空对象。Developer/Test 只能把 registry ID 交给 Skill 的 scripts/run_verification.py 执行，不直接拼接 path/args。检查脚本从项目根 cwd 或 ACK_PROJECT_ROOT 定位资源，不能依赖自身文件路径。 ACK_PROJECT_ROOT 是 runner 固定的根目录 fd 路径；仅用于日志的原始路径位于 ACK_PROJECT_ROOT_DISPLAY。

项目状态校验由 /ack 使用 Skill 自带的 scripts/validate_tasks.py 和 scripts/validate_knowledge.py 执行。

硬规则（其余见 references/）

三角色独立：Coordinator 只编排、Test 只验证、Developer 只实现（验证者 ≠ 实现者）。
模型分层：Coordinator 用强模型且不亲自跑测试，Test/Developer 用中低模型，必要时升级（见 references/model-routing.md）。
worker_done 与复测报告都不等于完成。必须 Test 独立复测 + Coordinator 终检后才能 verified。
只有 Coordinator 写 tasks.yaml 和 knowledge.yaml；Developer 与 Test 都只读，通过消息回报。
Coordinator 只派发按 scope 命中并显式写入 knowledgeRefs 的 active 知识； candidate 不派发，知识库不全量注入。
Developer 回报 knowledgeApplied 与 knowledgeCandidates，Test 回报 knowledgeChecks。关键约束应下沉为测试、lint、CI 或正式规范。
ACK 不自动修改 AGENTS.md、CLAUDE.md 或其它 Agent 指令文件。
每个任务最多派发 3 轮，仍不过标记 leftover 并继续下一个。
不提交或推送，除非用户明确要求。

4.7 KiB Raw Blame History Unescape Escape