harness_coding_docs/docs/00-ai-start-here.md

AI 开发入口

给 AI coding agent 的项目入口。这里负责导航和流程，硬性编码规则见 05-coding-rules.md。

一句话定位

【项目名】是【一句话说明项目目标、用户和 MVP 范围】。

第一版 MVP 只做：【列出最小闭环功能】。

上下文读取

首次接入、agent-context.json 缺失或校验失败时，按这个顺序建立完整上下文：

1. 01-vision.md：为什么做、为谁做、什么不做。
2. 02-requirements.md：MVP 要什么、怎么算达成。
3. 03-tech-stack.md：既定技术选型。
4. 04-architecture.md：系统结构、职责划分、数据模型和关键难点。
5. 05-coding-rules.md：写代码前必须遵守的规则。
6. 06-tasks.md：阶段路线图、里程碑和待办池。
7. tasks/README.md：任务文件约定（一任务一文件）；本轮任务从 docs/tasks/ 领取。
8. current-state.md：当前代码现实、可运行命令、下一步任务。

日常会话不需要机械重读全部文档：

1. 读取仓库级规则和 agent-context.json。
2. 读取 bootstrap.always_read。
3. 读取本轮任务文件 / Gitea Issue。
4. 按任务类型读取 routes 中的文档；一个文件命中多个路由时只读一次。
5. 记录默认分支头提交为 context_ref；同一会话中文件 SHA 未变化时复用已读内容。

清单的使用、缓存和断连降级规则见 agent-context.md。

../progress.md 为可选的历史归档 / 项目级大事记，仅在需要追溯早期历史时查阅。

如果仓库根目录有 AGENTS.md、CLAUDE.md 或其他 agent 规则文件，也必须先读。仓库级规则优先于项目局部建议。

固定开工流程

读完上述文档后，每轮会话按这个机械顺序进入，恢复持久状态再动手：

1. pwd：确认在正确的仓库根目录。
2. 读 current-state.md 和 docs/tasks/ 中当前 agent 的活跃任务；启用 Gitea 时同时读对应 Issue，恢复已验证状态、claim、下一步和当前 blocker。
3. git log --oneline -5：看清最近发生了什么。
4. 运行 ./init.sh（Windows 原生 PowerShell 用 ./init.ps1）：统一安装、验证、打印启动命令；如果脚本提示命令未替换，先配置脚本顶部三个命令。
5. 跑一条基础 smoke / 端到端路径，确认基线没坏。
6. 如果基线已坏，先修基线，不要在坏的起点上叠新功能。
7. 基线绿了，再从 docs/tasks/ 为当前 agent 领取唯一任务（路线图见 06-tasks.md）；启用 Gitea 时由 dispatcher 串行分配并取得原子 claim。

当前阶段

当前项目处于：【例如：MVP 起步 / 原型验证 / 功能开发 / 上线前收尾】。

优先路径：

1. Phase 0：最小可运行地基。
2. Phase 1：最高风险功能原型。
3. Phase 2：核心用户流程。
4. Phase 3：账号 / 数据持久化 / 同步。
5. Phase 4：部署、离线、监控或上线准备。

领取任务规则

任务以「一任务一文件」存放在 docs/tasks/（约定见 tasks/README.md）：

• 每个 agent 只领取一个 frontmatter status: TODO 且依赖均 DONE 的任务文件，取编号最靠前的；项目可并行多个 write_paths 互不重叠的任务。
• 若 docs/tasks/ 暂无可领任务，先按 06-tasks.md 路线图把下一个建议任务落成任务文件，再领取。
• 未启用 Gitea 时，开始前在独立分支 / worktree 把该文件 frontmatter 的 status 改为 DOING。
• 启用 Gitea 时，由 dispatcher 按 gitea-collaboration.md 串行检查写路径并原子创建 claims/T-<编号>；worker 只接受已读回确认的分配。标签、assignee 和更新后读回不能代替同任务领取锁。
• 本轮只完成这一个任务；验收通过后改为 DONE。
• 执行记录写进该任务文件的 ## 执行记录（改了什么、跑了什么验证、结果、决策）。
• 若项目现实发生变化（启动/验证路径、目录结构、blocker），覆盖更新 current-state.md；未启用 Gitea 时以任务文件 frontmatter 为状态权威，启用后以 Issue 为实时状态，不逐任务改写快照。
• 结束会话前过一遍 clean-state-checklist.md，确保下一轮无需人工修复即可开工。
• 做完即停，汇报验证结果，等待下一步指令。

本约定单 agent 与多 agent 并发通用；并发时遵守 tasks/README.md 的编号和写路径防撞规则，每个 agent 使用独立工作分支与 worktree。

如果代码实际状态和任务文件冲突，先说明冲突，不要擅自跳步或重排。

MVP 边界

MVP 只做：

• 【P0 功能 1】
• 【P0 功能 2】
• 【P0 功能 3】

MVP 不做：

• 【明确非目标 1】
• 【明确非目标 2】
• 【后续版本功能】

事实来源

项目事实只信：

• 【业务数据源 / schema / seed 数据路径】
• 【产品需求文档】
• 【接口合约】
• 【现有代码中的权威模块】

不要把以下内容当事实来源：

• 历史备份文件。
• 旧导出文档。
• 临时实验目录。
• 未被任务或需求引用的草稿。

常见任务该看哪里

做页面 / UI：

• 先看 02-requirements.md 的对应验收标准。
• 再看 routes.md 的页面职责。
• 最后看 04-architecture.md 的组件边界。

做后端 API：

• 先看 api.md 的接口合约。
• 再看 04-architecture.md 的数据模型和鉴权边界。

做本地工具 / CLI / 无后端项目：

• 先看 api.md 中的本地模块合约、CLI 参数或事件合约。
• 再看 04-architecture.md 的本地模块边界和数据流。

做数据模型：

• 先看 04-architecture.md 的数据模型。
• 如果 schema 变化，必须同步更新 api.md、current-state.md 和相关任务验收。

做部署 / 运行：

• 先看 03-tech-stack.md 的运行命令。
• 再看 current-state.md 的当前真实命令。

验证命令

统一启动与验证入口建议收敛到根目录 ./init.sh（Windows 原生 PowerShell 用 ./init.ps1，两者等价、按操作系统二选一），完成安装 + 基础验证 + 打印启动命令，避免每轮会话重新拼命令。脚本不绑定技术栈；复制到新项目后必须先替换脚本顶部三个命令变量，并把真实命令同步到 03-tech-stack.md 和 current-state.md。下面按场景把真实命令填全：

# 示例
npm test
npm run build
go test ./...
pytest

说明：

• 改前端后跑：【命令】。
• 改后端后跑：【命令】。
• 改数据结构后跑：【命令】。
• 如果命令当前不可运行，必须在回复里如实说明原因。