# AGENTS.md — cz-web 代码开发流程

本项目所有 AI 编码任务统一走以下流程。三个 skill 各司其职，**冲突时以 auto-dev 流程为主线、vue-project-structure 为结构裁决、karpathy-guidelines 为编码底线**。

## 一、三个 skill 的分工

| 角色 | Skill | 职责 | 何时加载 |
| ---- | ----- | ---- | -------- |
| **主流程** | [auto-dev](.claude/skills/auto-dev/SKILL.md) | 从原型/PRD/设计稿到可运行代码的完整管线（7 个阶段） | 提到"自动化开发、从原型生成代码、蓝湖生成页面、PRD 生成页面"时 |
| **项目规则** | [vue-project-structure](.claude/skills/vue-project-structure/SKILL.md) | 目录归属、三层数据流（页面 → store → api）、命名与文件作用 | **任何**新建/移动/修改 `src/` 下文件之前，必读 |
| **编码规则** | [karpathy-guidelines](.claude/skills/karpathy-guidelines/SKILL.md) | 少代码、外科手术式修改、可验证的成功标准 | 写代码、review、重构时始终生效 |

优先级：**项目规则（结构归属）> 编码规则（写法底线）**；auto-dev 只决定"做什么、按什么顺序做"，不覆盖前两者的规范。

## 二、标准代码流程

```
① 读取现状
   └─ 用 codegraph_files/glob 映射 src/ 结构，读目标文件及同级文件
      → verify: 能说出目标文件该放哪个目录、同名文件是否已存在

② 明确需求（karpathy §1）
   └─ 陈述假设；多种解释时先列出并确认；不清楚就停下来问
      → verify: 无隐含假设，成功标准可验证

③ 规划文件落位（vue-project-structure）
   └─ 对照"src/ 每个文件的作用"定位：
      接口 api/<page>.ts、数据 stores/modules/<page>.ts、
      页面 views/<page>/、类型 types/business/<page>.d.ts 四者同名
      → verify: 目录归属正确，不新建顶层目录

④ 编写/修改代码（auto-dev 阶段四~五 + karpathy §2/§3）
   └─ 数据流铁律：页面 → store → api 单向，页面禁止 import api
      组件两级归属：≥2 页面复用 → components/；单页独有 → views/<page>/cpns/
      最小改动：只改与需求相关的行，不顺手重构
      → verify: 每一行改动都能追溯到用户需求

⑤ 测试（karpathy §4）
   └─ 测试文件统一放 src/tests/，镜像源码结构
      （src/utils/format.ts → src/tests/utils/format.test.ts）
      → verify: 测试通过

⑥ 验证与修正（auto-dev 阶段七）
   └─ pnpm build（含 vue-tsc 类型检查）零错误
      逐条核对 vue-project-structure 的"修改代码强制检查清单"
      → verify: build 退出码 0、检查清单全过
```

## 三、硬性约束（任一违反即返工）

1. 页面禁止 `import` api 层；数据必须经 store。
2. 禁止 `as any` / `@ts-ignore` / `@ts-expect-error`。
3. 导入一律 `@/` 别名，禁止跨目录相对路径（`../` 超过一层即违规）。
4. 样式只用 less，色值取自 `styles/variables.less`，禁止魔法值。
5. 不顺手"改进"无关代码；与本次需求无关的死代码只报告、不删除。
6. 测试文件只放 `src/tests/`，不与源码混放。
7. 收尾必须跑 `pnpm build`，零错误才算完成。

## 四、触发速查

| 用户说 | 加载 |
| ------ | ---- |
| 自动化开发 / 原型生成代码 / 蓝湖 / PRD 生成页面 | auto-dev（主）+ vue-project-structure |
| 新增/修改 `src/` 下任何文件、新文件放哪 | vue-project-structure |
| 写代码 / 改代码 / 重构 / review | karpathy-guidelines |