CLAUDE.md — ERP项目 Claude Code 主指令文件

本文件是 Claude Code 的"操作手册"。Claude Code 启动时会自动读取此文件。

---

🎯 项目概述

• 项目名称: 【人工填写：公司 + 项目名，例如"XX 公司 ERP 管理系统"】
• 项目简述: 【人工填写：一句话描述项目目标，例如"面向中小制造企业的全流程 ERP，涵盖采购/库存/生产/销售/财务"】
• 目标用户: 【人工填写：谁会用，例如"企业内部管理人员（采购员、仓管员、生产主管、销售员、财务人员、管理层）"】
• 部署方式: 【人工填写：私有化部署 / 云部署 / Docker 容器化 等】

---

🔄 编码开发流程（两阶段 + 统一功能循环）

编码阶段入口：/erp-workflow:coding-start。lite 保留后端模块阶段与前端整体阶段两段，但两段共用同一套功能循环 skill（feature-spec → feature-tdd → feature-review），由 phase 参数区分。

阶段路由（coding-start 内，只做分发）

coding-start 每次入口按"先后端、再前端"检查并派发到 phase-driver：

1. 扫 docs/08 § 二 各后端模块 里程碑: 字段 + git tag -l 'milestone/<id>'：有未打里程碑模块 → 派发 phase-driver（phase=backend），结束。
2. 后端全部打里程碑 → 读 docs/08 § 三 整体里程碑: + git tag -l 'milestone/frontend-phase'：未完成 → 派发 phase-driver（phase=frontend），结束。
3. 后端 + 前端都完成 → 输出"所有阶段已完成"。

统一功能循环（两阶段共用）

阶段驱动（外）：phase-driver（phase=backend 走后端模块；phase=frontend 走前端整体阶段——自带 prototype/ 门禁 + 从 prototype/docs01/docs05 推导 FE 清单写入 docs/08 § 三）→ feature 循环 → milestone（本地 merge 进默认分支 + 打 milestone/<id> 或 milestone/frontend-phase tag）→ 自动回调 coding-start 路由下一阶段（无人工介入）。

功能循环（内，每个 REQ-XXX-NNN 或 FE-NN 一遍）：feature-spec → feature-tdd → feature-review。

• phase=backend：单元是 REQ，分支 module-<id>，产出 controller/service/repository/DTO/migration；
• phase=frontend：单元是 FE，分支 frontend-phase，产出 frontend/ 下组件/路由/API client（以 prototype 为页面权威）；
• feature-review verdict=approve → 勾选 docs/08 § 二（后端 REQ）/ § 三（前端 FE）对应子项，继续下一单元；
• 本阶段单元全部完成 → 调用 milestone 打里程碑 tag + 回调 coding-start。

里程碑前守门

• milestone 在打 tag 前内置测试闸门（phase 由分支推断：后端 scripts/test.sh；前端 vitest + Playwright，命令取自 docs/04 § 零）；红色不得跳过。
• 测试 / 验证统一派发到 Agent 子会话执行，主会话只接收结构化结论。

---

✅ 阶段完成判定规则

docs/08-模块任务管理.md 分三段：

• § 一：计划阶段三段（①②③）进度勾选
• § 二：后端编码模块元数据表（每个模块一行 bullet，记录依赖 / 路径 / 里程碑 tag / REQ 功能子项；行序即 REQ 开发顺序，是 phase-driver 的排序权威）
• § 三：前端整体阶段（整体里程碑: 字段 + FE 功能清单，由 phase-driver(phase=frontend) 推导填入）

阶段完成判定统一以 里程碑: 字段（§二 模块 / §三 整体）+ 本地 git tag -l 'milestone/<id>' 判定；子项勾选只作可视化进度，不参与完成判定。

后端模块格式

每个后端模块在 docs/08 § 二 中长这样：

- module_0 系统管理
  - 依赖: —
  - 路径: backend/module/sys/
  - 里程碑: —
  - 功能:
    - [ ] REQ-SYS-001 用户登录
    - [ ] REQ-SYS-002 用户注册

• 里程碑: 字段由 milestone 在打里程碑 tag 时从 — 改为 milestone/<module_id>。
• 每个 REQ-* 子项由 feature-review 在 verdict=approve 时自动勾选为 [x]。

状态语义

里程碑: 字段	git tag -l	含义	你（Claude Code）的行为
—	tag 不存在	该阶段未开始 / 进行中（未打里程碑）	✅ 开始 / 继续该阶段开发
milestone/<id>	tag 存在	阶段已完成	🟢 进入下一未完成模块；全部完成 → 输出完成信息

模块完成报告

由 milestone skill 产出，模板由 milestone skill 持有。CC 不手写模块报告，仅填模板。

---

🏷️ 占位符统一约定

项目文档里有 2 种填写占位 + 1 种提示占位：

格式	谁填	使用阶段	说明
【人工填写：<简短说明>】	人	仅计划阶段文档	密钥 / 账密 / 包名 / 命名约定 / 小版本号等人工才能决定的值；编码阶段 plan/spec 禁止出现，查不到真值时用 AskUserQuestion 问用户
TBD(<责任人>)	CC 自动	计划或编码	后缀附带责任方（如 TBD(lite-design 自动补) / TBD(lite-build-db 自动补)）；由对应 skill 就地补填

HTML 注释 <!-- ... -->：提示占位，是插件内部大纲模板里给 LLM 的填空提示 / 章节引导，指引 LLM 按结构填实际内容。skill 生成时会剥除这些注释，最终产物里注释不会保留。

---

📐 编码行为约束

你必须做的 ✅

1. 严格遵循 docs/04-技术规范.md——命名 / 编码 / 统一响应 / 异常处理 / 数据访问 / 配置与安全 / 环境配置（含 .env.local 字段说明）等项目专属技术规约全部在此
2. 每个后端接口 必须先在 docs/05-API接口契约.md 定义，再编码实现
3. 每个功能可追溯到 REQ-XXX-NNN——commit tag + 代码注释（如 // REQ-SYS-001: 用户登录）+ plan/spec 文件名均用此 tag
4. 遇到跨模块改动（动到非当前模块的代码）——按 § 🟡 软规则 S2 执行（允许改，但必须留痕）
5. 遇到技术栈外组件引入（docs/04 § 零 技术栈表外的框架 / 中间件 / 关键库），按 § 🟡 软规则 S1 执行（允许引入，但必须先 AskUserQuestion）

你禁止做的 🚫

1. 主会话直接 mysql -e 跑业务 DDL（只读查询 / 临时本地调试除外）——业务 schema 必须走 sql/migrations/V_n__*.sql，详见下方 Schema 演化规约
2. 手动 Edit docs/08 § 二 的 里程碑: 字段，必须由 milestone 自动回写

Schema 演化规约（Flyway migration）

1. 文件命名：sql/migrations/V<n>__<snake_case_desc>.sql，例：V5__add_user_email_unique_index.sql
2. 版本号分配：建文件前 ls sql/migrations/V*.sql 查当前最大 n，新文件 n_max + 1
3. Apply 方式：Spring Boot 启动 / 测试启动时 Flyway 自动 apply（项目必须在 pom.xml 声明 flyway-core + flyway-mysql 依赖）。scripts/setup-test-db.sh 只负责清空库，不做 apply
4. 已合并的 migration 永不修改：发现错了写一个补救 migration（如 V7__fix_V5_index_name.sql），旧 V_n.sql 不动
5. 临时调试 DDL：临时在本地试字段/索引可手动 mysql -e，但不写 migration；下次 setup-test-db.sh 会 drop+create 清掉
6. 计划 ③ 生成的 V1：V1__initial_schema.sql 是计划阶段由 lite-build-db 从 docs/03-数据库设计文档.md（lite-design 正向设计的 schema SSoT）翻译生成的初始版本；后续 V2/V3/... 由编码阶段每个 REQ 按需写入，同时反向同步更新 docs/03 对应表小节以保持 SSoT 一致

---

🗂️ Git 提交规范

每次提交必须遵循以下格式：

<type>(<scope>): <subject>

• scope: 模块名，如 user / inventory / order
• subject: 简短描述；业务类（feat / fix / test）必须带 REQ-XXX-NNN 后缀

type 含义：

type	看到它意味着
feat	新能力上线——用户多了一个功能、接口、页面或业务规则
fix	修 bug——原来行为错了，这次改对
refactor	重构——外部行为不变，只改代码结构 / 命名 / 抽象
docs	文档改动——只动 Markdown / 代码注释，不动实现
style	格式调整——空白 / 缩进 / import 顺序，逻辑 0 变化
test	只动测试代码——补用例 / 修 fixture，不碰实现
chore	流程维护——构建 / 依赖 / 工具 / 证据档案 / 里程碑元数据等非业务动作

---

🚩 中断机制

功能循环（每个功能 REQ-XXX 的 feature-spec → feature-tdd → feature-review）默认 静默编程，但触发以下任何一条必须立刻停下、记录原因、等人决策，不得自行绕过：

| # | 中断 | 例子 | | - | --- | --- | | 1 | 测试反复失败 | 同一测试同一功能内连续 10 次修复失败 | | 2 | 要改密钥 / 账密 / 包名 | 涉及 .env.local / docs/04 §零环境 中的密钥/账密字段 | | 3 | 外部接口不可达 | 第三方 API 无法连接、证书失效等环境问题，并无法自行解决 |

其余需要人类判断的场景一律走普通 AskUserQuestion Q&A，不中断、不写 Blocker 文件。

触发中断时的固定动作：

1. 在当前功能的 spec 文件里追加一节 ## 🚩 Blocker（报告格式由 interrupt-check 的 interrupt-block-template.md 持有）
2. 停止后续所有功能的静默执行
3. 在主会话输出一句话摘要 + 指向 blocker 文件的路径，等人回复

---

🟡 软规则（允许继续，但有强制后续动作）

以下情况 不触发中断，CC 可自行继续推进，但必须在约定位置留痕，模块完成时统一审计。

| # | 软规则 | 允许动作 | 强制后续 | | - | ----- | ------- | ------- | | S1 | 技术栈外组件引入 | 用 AskUserQuestion 给用户三选一：接受引入 / 换方案 / 拒绝 | ① 接受 → 同会话直接在 docs/04 § 零 追加一行 → 继续流程 ② 换方案 / 拒绝 → 视为常规歧义澄清，继续 Q&A 收敛 ③ 不写 Blocker、不中断流程 | | S2 | 跨模块改动 | 默认不改，仅为当前模块实现所必需时允许修改 | 在该模块 milestone 完成报告的「⑤ 偏离与取舍」节如实记录改了哪个非当前模块的文件 + 原因（lite 无自动留痕 hook，靠报告人工记录） |

---

🧭 通用工作准则（General Principles）

1. Think Before Coding

Don't assume. Don't hide confusion. Surface tradeoffs.

Before implementing:

• State your assumptions explicitly. If uncertain, ask.
• If multiple interpretations exist, present them - don't pick silently.
• If a simpler approach exists, say so. Push back when warranted.
• If something is unclear, stop. Name what's confusing. Ask.

2. Simplicity First

Minimum code that solves the problem. Nothing speculative.

• No features beyond what was asked.
• No abstractions for single-use code.
• No "flexibility" or "configurability" that wasn't requested.
• No error handling for impossible scenarios.
• If you write 200 lines and it could be 50, rewrite it.

Ask yourself: "Would a senior engineer say this is overcomplicated?" If yes, simplify.

3. Surgical Changes

Touch only what you must. Clean up only your own mess.

When editing existing code:

• Don't "improve" adjacent code, comments, or formatting.
• Don't refactor things that aren't broken.
• Match existing style, even if you'd do it differently.
• If you notice unrelated dead code, mention it - don't delete it.

When your changes create orphans:

• Remove imports/variables/functions that YOUR changes made unused.
• Don't remove pre-existing dead code unless asked.

The test: Every changed line should trace directly to the user's request.

4. Goal-Driven Execution

Define success criteria. Loop until verified.

Transform tasks into verifiable goals:

• "Add validation" → "Write tests for invalid inputs, then make them pass"
• "Fix the bug" → "Write a test that reproduces it, then make it pass"
• "Refactor X" → "Ensure tests pass before and after"

For multi-step tasks, state a brief plan:

1. [Step] → verify: [check]
2. [Step] → verify: [check]
3. [Step] → verify: [check]

Strong success criteria let you loop independently. Weak criteria ("make it work") require constant clarification.

---

🗺️ Skill 索引（erp-workflow-lite，共 11 个）

入口

Skill	描述
plan-start	计划阶段入口——扫 docs/08 § 一找第一个未完成计划段（①②③）并派发
coding-start	编码阶段入口 + 阶段分发器——先后端（docs/08 § 二）后前端（§ 三），派发 phase-driver(phase=backend/frontend)；都完成则输出全部完成

计划阶段

Skill	描述
lite-init	计划 ①——项目初始化 + 范围锁定（模板复制、依赖检查、git init、项目概述+技术栈+需求索引、REQ 卡片生成，停下等人工审阅）
lite-design	计划 ②——脚手架 + 数据库设计（docs/04 § 一+、scripts、.env.local、docs/03 DB 设计，停下等人工审阅）
lite-build-db	计划 ③——DB 初始化 + 下游文档（V1 migration apply、docs/05 API 契约、docs/08 § 二模块清单，计划阶段结束）

编码阶段

Skill	描述
phase-driver	阶段驱动（phase 参数区分）——backend：加载当前模块 REQ 清单逐个派发；frontend：prototype/ 门禁 + 推导 FE 清单写 docs/08 § 三后逐个派发
feature-spec	功能规格（两阶段共用）——为 REQ（后端）/ FE（前端）生成"规格 + 任务级计划"合并文档
feature-tdd	TDD 实现（两阶段共用）——按 plan 测试先行再实现，Agent 子会话跑测试；路径护栏按 phase 区分
feature-review	验证 + AI 自审（两阶段共用）——子会话跑测试 + reviewer agent（后端 superpower / 前端 fe-code-reviewer），approve 勾选进度回 phase-driver
milestone	里程碑（phase 由分支推断）——内置测试闸门（Agent 子会话），green 则本地 merge + 打 tag，生成完成报告

守门

Skill	描述
interrupt-check	中断检查——触发中断条件时由功能循环 skill 调用，追加 Blocker 节并停止执行

文档套件（5 文档）

文档	职责
docs/01-需求清单/	REQ 卡片目录（模块子目录 + index.md）
docs/03-数据库设计文档.md	表/字段/索引/外键 SSoT（lite-design 生成，编码阶段同步更新）
docs/04-技术规范.md	技术栈总览（§ 零）+ 架构规范 + 前端 Design Tokens / 交互约定 + 环境变量说明（含 .env.local 密钥字段）——lite 把原 UI 规范与环境配置并入此文件
docs/05-API接口契约.md	所有后端接口契约（lite-build-db 生成，feature-spec 按需追加）
docs/08-模块任务管理.md	全流程进度跟踪（§ 一计划 / § 二后端模块 / § 三前端整体）