173 lines
9.0 KiB
Markdown
173 lines
9.0 KiB
Markdown
# AI 开发入口
|
||
|
||
> 给 AI coding agent 的项目入口。这里负责导航和流程，硬性编码规则见 [`05-coding-rules.md`](05-coding-rules.md)。
|
||
|
||
## 一句话定位
|
||
|
||
【项目名】是【一句话说明项目目标、用户和 MVP 范围】。
|
||
|
||
第一版 MVP 只做：【列出最小闭环功能】。
|
||
|
||
## 上下文读取
|
||
|
||
首次接入、[`agent-context.json`](agent-context.json) 缺失或校验失败时，按这个顺序建立完整上下文：
|
||
|
||
1. [`01-vision.md`](01-vision.md)：为什么做、为谁做、什么不做。
|
||
2. [`02-requirements.md`](02-requirements.md)：MVP 要什么、怎么算达成。
|
||
3. [`03-tech-stack.md`](03-tech-stack.md)：既定技术选型。
|
||
4. [`04-architecture.md`](04-architecture.md)：系统结构、职责划分、数据模型和关键难点。
|
||
5. [`05-coding-rules.md`](05-coding-rules.md)：写代码前必须遵守的规则。
|
||
6. [`06-tasks.md`](06-tasks.md)：阶段路线图、里程碑和待办池。
|
||
7. [`tasks/README.md`](tasks/README.md)：任务文件约定（一任务一文件）；本轮任务从 `docs/tasks/` 领取。
|
||
8. [`current-state.md`](current-state.md)：当前代码现实、可运行命令、下一步任务。
|
||
|
||
若项目有页面、表单、移动端、桌面端或其他用户交互界面，首次接入还必须完成[用户故事清单](07-user-stories.md)和[交互清单](08-interaction-checklist.md)，再开始拆 UI 任务。
|
||
|
||
日常会话不需要机械重读全部文档：
|
||
|
||
1. 读取仓库级规则和 [`agent-context.json`](agent-context.json)。
|
||
2. 读取 `bootstrap.always_read`。
|
||
3. 读取本轮任务文件 / Gitea Issue。
|
||
4. 按任务类型读取 `routes` 中的文档；一个文件命中多个路由时只读一次。
|
||
5. 记录默认分支头提交为 `context_ref`；同一会话中文件 SHA 未变化时复用已读内容。
|
||
|
||
清单的使用、缓存和断连降级规则见 [`agent-context.md`](agent-context.md)。
|
||
|
||
`../progress.md` 为可选的历史归档 / 项目级大事记，仅在需要追溯早期历史时查阅。
|
||
|
||
如果仓库根目录有 `AGENTS.md`、`CLAUDE.md` 或其他 agent 规则文件，也必须先读。仓库级规则优先于项目局部建议。
|
||
|
||
## 固定开工流程
|
||
|
||
读完上述文档后，每轮会话按这个机械顺序进入，恢复持久状态再动手：
|
||
|
||
1. `pwd`：确认在正确的仓库根目录。
|
||
2. 读 [`current-state.md`](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`](06-tasks.md)）；启用 Gitea 时由 dispatcher 串行分配并创建 claim 标记。
|
||
|
||
## 工作模式（跨 Agent 通用）
|
||
|
||
以下规则面向 Claude Code、Codex 及其他 coding agent。共享文档描述职责和交付约束，不绑定厂商、模型名称或平台专有的代理类型。
|
||
|
||
- 默认采用**单任务、单责任 Agent、单写入者**：一个任务只有一个对结果负责的 Agent，同时只有一个 Agent 修改该任务的 `write_paths`。多 Agent 并行优先拆到写路径互不重叠的不同任务。
|
||
- 复杂任务先规划再编码。确认后的方案、不可变约束、写路径和验收门禁必须写入当前任务文件，不能只停留在对话或平台的临时规划界面。
|
||
- 范围明确时由责任 Agent 直接查证和执行；只有范围不清、需要跨目录扇出，且只读探索能明显减少试错时，才按当前平台能力使用只读探索。探索结果回填任务文件后再进入实现。
|
||
- 任务内委派不是默认流程。只有项目规则显式允许且收益明确时才启用；委派后仍保持唯一写入者，执行者必须继承任务文件中的不可变约束、`write_paths` 和验证要求。
|
||
- 无论是否委派，任务所有者都对最终结果负责，并按 [`05-coding-rules.md`](05-coding-rules.md) 独立审阅差异、重跑验证；不能把执行者或工具的自我报告当成完成证据。
|
||
|
||
厂商或平台专属的模型分工、代理名称和权限配置，应只放在对应的本机配置或薄入口中；通用任务流程仍以仓库级规则和本目录文档为准。
|
||
|
||
## 当前阶段
|
||
|
||
当前项目处于：【例如：MVP 起步 / 原型验证 / 功能开发 / 上线前收尾】。
|
||
|
||
优先路径：
|
||
|
||
1. Phase 0：最小可运行地基。
|
||
2. Phase 1：最高风险功能原型。
|
||
3. Phase 2：核心用户流程。
|
||
4. Phase 3：账号 / 数据持久化 / 同步。
|
||
5. Phase 4：部署、离线、监控或上线准备。
|
||
|
||
## 领取任务规则
|
||
|
||
任务以「一任务一文件」存放在 `docs/tasks/`（约定见 [`tasks/README.md`](tasks/README.md)）：
|
||
|
||
- 每个 agent 只领取一个 frontmatter `status: TODO` 且依赖均 `DONE` 的任务文件，取编号最靠前的；项目可并行多个 `write_paths` 互不重叠的任务。
|
||
- 若 `docs/tasks/` 暂无可领任务，先按 [`06-tasks.md`](06-tasks.md) 路线图把下一个建议任务落成任务文件，再领取。
|
||
- 未启用 Gitea 时，开始前在独立分支 / worktree 把该文件 frontmatter 的 `status` 改为 `DOING`。
|
||
- 启用 Gitea 时，由 dispatcher 按 [`gitea-collaboration.md`](gitea-collaboration.md) 串行检查写路径并创建 `claims/T-<编号>` 防御性标记；worker 只接受已读回确认的分配。不要把标签、assignee、读回或普通 create-branch API 单独当作并发锁。
|
||
- 本轮只完成这一个任务；验收通过后改为 `DONE`。
|
||
- **执行记录写进该任务文件的 `## 执行记录`**（改了什么、跑了什么验证、结果、决策）。
|
||
- 若项目现实发生变化（启动/验证路径、目录结构、blocker），覆盖更新 [`current-state.md`](current-state.md)；未启用 Gitea 时以任务文件 frontmatter 为状态权威，启用后以 Issue 为实时状态，不逐任务改写快照。
|
||
- 结束会话前过一遍 [`clean-state-checklist.md`](clean-state-checklist.md)，确保下一轮无需人工修复即可开工。
|
||
- 做完即停，汇报验证结果，等待下一步指令。
|
||
|
||
> 本约定单 agent 与多 agent 并发通用；并发时遵守 [`tasks/README.md`](tasks/README.md) 的编号和写路径防撞规则，每个 agent 使用独立工作分支与 worktree。
|
||
|
||
如果代码实际状态和任务文件冲突，先说明冲突，不要擅自跳步或重排。
|
||
|
||
## MVP 边界
|
||
|
||
MVP 只做：
|
||
|
||
- 【P0 功能 1】
|
||
- 【P0 功能 2】
|
||
- 【P0 功能 3】
|
||
|
||
MVP 不做：
|
||
|
||
- 【明确非目标 1】
|
||
- 【明确非目标 2】
|
||
- 【后续版本功能】
|
||
|
||
## 事实来源
|
||
|
||
项目事实只信：
|
||
|
||
- 【业务数据源 / schema / seed 数据路径】
|
||
- 【产品需求文档】
|
||
- 【接口合约】
|
||
- 【现有代码中的权威模块】
|
||
|
||
不要把以下内容当事实来源：
|
||
|
||
- 历史备份文件。
|
||
- 旧导出文档。
|
||
- 临时实验目录。
|
||
- 未被任务或需求引用的草稿。
|
||
|
||
## 常见任务该看哪里
|
||
|
||
做页面 / UI：
|
||
|
||
- 先看 `02-requirements.md` 的对应验收标准。
|
||
- 再看 `07-user-stories.md` 的用户目标和验收场景。
|
||
- 再看 `08-interaction-checklist.md` 的关联 IX 条目、状态和无障碍要求。
|
||
- 再看 `routes.md` 的页面职责。
|
||
- 最后看 `04-architecture.md` 的组件边界。
|
||
- 若 `docs/design/` 有关联原型，可作为页面结构参考；行为以交互清单为准，不复制原型代码（约定见 [`design/README.md`](design/README.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`。下面按场景把真实命令填全：
|
||
|
||
```bash
|
||
# 示例
|
||
npm test
|
||
npm run build
|
||
go test ./...
|
||
pytest
|
||
```
|
||
|
||
说明：
|
||
|
||
- 改前端后跑：【命令】。
|
||
- 改后端后跑：【命令】。
|
||
- 改数据结构后跑：【命令】。
|
||
- 如果命令当前不可运行，必须在回复里如实说明原因。
|