5.0 KiB
5.0 KiB
AI 开发入口
给 AI coding agent 的项目入口。这里负责导航和流程，硬性编码规则见
05-coding-rules.md。
一句话定位
【项目名】是【一句话说明项目目标、用户和 MVP 范围】。
第一版 MVP 只做：【列出最小闭环功能】。
必读顺序
每次开始写代码前，按这个顺序建立上下文：
01-vision.md：为什么做、为谁做、什么不做。02-requirements.md：MVP 要什么、怎么算达成。03-tech-stack.md：既定技术选型。04-architecture.md：系统结构、职责划分、数据模型和关键难点。05-coding-rules.md：写代码前必须遵守的规则。06-tasks.md：领取本轮唯一任务。../progress.md：历史执行记录、验证结果、阻塞点和关键决策。current-state.md：当前代码现实、可运行命令、下一步任务。
如果仓库根目录有 AGENTS.md、CLAUDE.md 或其他 agent 规则文件，也必须先读。仓库级规则优先于项目局部建议。
固定开工流程
读完上述文档后，每轮会话按这个机械顺序进入，恢复持久状态再动手：
pwd：确认在正确的仓库根目录。- 读
../progress.md和current-state.md：恢复已验证状态、下一步和当前 blocker。 git log --oneline -5：看清最近发生了什么。- 运行
./init.sh（Windows 原生 PowerShell 用./init.ps1）：统一安装、验证、打印启动命令；如果脚本提示命令未替换，先配置脚本顶部三个命令。 - 跑一条基础 smoke / 端到端路径，确认基线没坏。
- 如果基线已坏，先修基线，不要在坏的起点上叠新功能。
- 基线绿了，再从
06-tasks.md领取唯一任务。
当前阶段
当前项目处于：【例如：MVP 起步 / 原型验证 / 功能开发 / 上线前收尾】。
优先路径：
- Phase 0：最小可运行地基。
- Phase 1：最高风险功能原型。
- Phase 2：核心用户流程。
- Phase 3：账号 / 数据持久化 / 同步。
- Phase 4：部署、离线、监控或上线准备。
领取任务规则
从 06-tasks.md 领取任务时：
- 只领取第一个状态为
TODO且依赖均为DONE的任务。 - 开始前把该任务状态改为
DOING。 - 本轮只完成这一个任务。
- 验收通过后把状态改为
DONE。 - 完成后把执行记录追加到
../progress.md，并覆盖更新current-state.md的当前快照。 - 结束会话前过一遍
clean-state-checklist.md，确保下一轮无需人工修复即可开工。 - 做完即停，汇报验证结果，等待下一步指令。
如果代码实际状态和任务看板冲突，先说明冲突，不要擅自跳步或重排。
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
说明：
- 改前端后跑：【命令】。
- 改后端后跑：【命令】。
- 改数据结构后跑：【命令】。
- 如果命令当前不可运行，必须在回复里如实说明原因。