已有项目接入清单

用于把本模板补进一个已经存在的项目。目标是先建立 agent 可读的事实来源，再继续开发新功能。

适用场景

项目已经有代码，但缺少清晰的 agent 入口、任务文件、当前状态和验证路径。
项目被多轮 AI 修改过，文档、代码和真实可运行状态已经不一致。
想从“靠聊天记录推进”切换到“靠仓库内工件推进”。

如果是全新空项目，优先按根目录 README.md 的“空项目接入”流程复制模板。

最小接入文件

先复制或建立这些文件：

文件	作用
`AGENTS.md`	仓库级 agent 入口和总规则
`CLAUDE.md`	Claude Code 薄入口，指向 `AGENTS.md`
`docs/00-ai-start-here.md`	每轮开工流程
`docs/agent-context.json`	按任务类型选择本轮上下文
`docs/agent-context.schema.json`	上下文清单结构契约
`docs/agent-context.md`	清单读取、缓存和断连降级规则
`docs/05-coding-rules.md`	编码纪律和验证底线
`docs/06-tasks.md`	任务路线图（阶段、里程碑、待办池）
`docs/tasks/`	默认任务管理：一任务一文件（`README.md` + `_template.md`）
`docs/current-state.md`	当前实现状态快照
`init.sh` 或 `init.ps1`	标准启动与验证入口，按操作系统二选一
`scripts/validate_agent_context.py`	零第三方依赖校验清单和引用路径

推荐随后补齐：docs/01-vision.md、docs/02-requirements.md、docs/03-tech-stack.md、docs/04-architecture.md、docs/api.md、docs/routes.md、docs/clean-state-checklist.md；有 UI / UX 的项目再补 docs/07-user-stories.md 与 docs/08-interaction-checklist.md；progress.md 可选（历史归档 / 项目级大事记）。

需要 Gitea 多 Agent 协作时，再复制 docs/gitea-mcp.md、docs/gitea-collaboration.md、.gitea/ 模板、scripts/setup_gitea_labels.py、scripts/audit_gitea_coordination.py、离线治理脚本和测试；先只读预览远端标签差异，再由维护者显式 --apply。Actions 工作流仅在仓库已启用 Actions 且 runner 可用时生效。

接入步骤

确认仓库根目录，读取已有 README、运行脚本、测试配置和主要入口文件。
复制最小接入文件，把所有 【占位符】 替换成当前项目事实，并按项目任务类型调整 agent-context.json 的路由。
在 docs/current-state.md 写清真实目录、真实启动命令、真实验证命令、当前 blocker。
在 docs/03-tech-stack.md 固定已经实际使用的技术栈，不确定项标为“待定”，不要让 agent 自行选择。
在 docs/04-architecture.md 记录当前代码的真实模块边界；不清楚的地方标为“待确认”。
在 docs/06-tasks.md 只放下一阶段能小步交付的建议任务，不要把历史愿望清单全部搬进去；第一轮任务按 docs/tasks/README.md 落成 docs/tasks/T-<编号>.md。
配置 init.sh 或 init.ps1 顶部三个命令，让它能安装依赖、运行基础验证、打印启动命令。
运行 python scripts/validate_agent_context.py 和项目标准验证；如果失败，第一轮任务应先修基线，不做新功能。
把接入过程、验证结果写进第一轮任务文件的 ## 执行记录，遗留 blocker 同步到 docs/current-state.md。

第一轮 agent 任务建议

已有项目接入后的第一轮，不建议直接做新功能。推荐任务是：

ID	任务	验收要点
T-000	建立当前状态基线	`current-state.md` 写清真实状态；`init` 脚本已配置；基础验证结果已记录到本任务文件的 `## 执行记录`
T-001	修复启动 / 验证基线	标准启动路径和标准验证路径可运行；失败原因已消除或记录为 blocker
T-002	对齐任务路线图	`06-tasks.md` 只保留可小步交付的建议任务；第一个待落地任务依赖清楚、验收可观察

代码现实与文档冲突时

以当前可运行代码和真实验证结果为事实起点。
文档描述旧功能但代码不存在时，先把差异记录到 current-state.md，不要直接补实现。
代码已有行为但文档没写时，先补 02-requirements.md、04-architecture.md 或 api.md，再继续修改代码。
命令不可运行时，不要标记任务完成；在当前任务文件的 ## 执行记录 记录失败命令和错误摘要。

不建议做的事

不要一次性把所有模板都填满；先让入口、当前状态、任务和验证路径可用。
不要把聊天记录当事实来源。
不要为了让验证通过而降低测试或验收标准。
不要在接入 harness 的同一轮顺手重构业务代码，除非是修复启动或验证基线所必需。

4.8 KiB Raw Permalink Blame History Unescape Escape