66 lines
3.5 KiB
Markdown
66 lines
3.5 KiB
Markdown
# 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 |
|