cz-web/AGENTS.md

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

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

一、三个 skill 的分工

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