# AI 开发入口

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

## 一句话定位

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

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

## 必读顺序

每次开始写代码前，按这个顺序建立上下文：

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. [`../progress.md`](../progress.md)：历史执行记录、验证结果、阻塞点和关键决策。
8. [`current-state.md`](current-state.md)：当前代码现实、可运行命令、下一步任务。

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

## 固定开工流程

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

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

## 当前阶段

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

优先路径：

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

## 领取任务规则

从 [`06-tasks.md`](06-tasks.md) 领取任务时：

- 只领取第一个状态为 `TODO` 且依赖均为 `DONE` 的任务。
- 开始前把该任务状态改为 `DOING`。
- 本轮只完成这一个任务。
- 验收通过后把状态改为 `DONE`。
- 完成后把执行记录追加到 [`../progress.md`](../progress.md)，并覆盖更新 [`current-state.md`](current-state.md) 的当前快照。
- 结束会话前过一遍 [`clean-state-checklist.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`。下面按场景把真实命令填全：

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

说明：

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