diff --git a/README.md b/README.md index bd982e9..625af33 100644 --- a/README.md +++ b/README.md @@ -84,6 +84,33 @@ include_frontend=false → 所有 frontend*.md 排除 --- +## 按规则生成功能:`/new-feature` + +生成的项目自带一个 Claude Code 命令 `/new-feature`,把"按规则搭功能骨架"固化成一条标准提示词。 + +``` +/new-feature 订单 +/new-feature 用户认证 +``` + +**模式:纯结构 + 契约(不猜业务逻辑)。** Claude 现场阅读本项目的 `.claude/rules`,按六边形分层为该功能生成跨层的**文件骨架**: + +``` +domain/(实体+值对象+端口 Protocol) → application/services → infrastructure/db(repository) + → routers → 依赖注入;前端 types/schemas → store → hooks → components +``` + +- 每个方法写**完整签名 + docstring(前置/后置条件)**,方法体留 `raise NotImplementedError` +- 接好依赖注入、注册路由、登记错误码 +- **不臆造业务逻辑、不写假设断言的测试**——避免你去调试 AI 猜的代码 +- 自检只跑 `ruff + mypy`(验证结构能编译、类型自洽),不跑 pytest + +命令按选型自动裁剪,只生成存在服务对应的层,末尾给出**待填充 TODO 清单**。 + +> 分工:脚手架预生成 `core/` 等可运行 plumbing;`/new-feature` 引导 Claude 搭**结构正确、契约清晰、零需调试**的骨架;业务逻辑你按 `testing-tdd.md`(先测试后实现)自己填。 + +--- + ## 脚手架内容 ``` @@ -106,6 +133,8 @@ scaffold/ │ └── tasks.json.jinja ← 自动 watch(仅 vscode_auto_watch=true) ├── docker-compose.yml.jinja ├── CLAUDE.md.jinja ← 项目说明参数化 + ├── .claude/commands/ + │ └── new-feature.md.jinja ← 项目内命令:按规则引导生成功能分层代码 ├── .claude/rules/ │ ├── # 原理层(10 个,静态,始终复制) │ ├── architecture.md / ddd.md / design-discipline.md ... diff --git a/template/.claude/commands/new-feature.md.jinja b/template/.claude/commands/new-feature.md.jinja new file mode 100644 index 0000000..e53423b --- /dev/null +++ b/template/.claude/commands/new-feature.md.jinja @@ -0,0 +1,69 @@ +按本项目的 `.claude/rules` 规则,为一个功能生成跨层的**结构与契约骨架**(垂直切片)。 + +功能:$ARGUMENTS + +这是 **AI 引导**的脚手架命令:你(Claude)现场阅读规则并生成符合分层约束的代码结构,而非套用固定模板。 + +**模式:纯结构 + 契约。** 只生成低风险、规则定死的部分(目录、文件、端口、方法签名、依赖注入、错误码登记);**不要猜测业务逻辑**——方法体一律留 `raise NotImplementedError` / `# TODO`,由开发者后续填充。不要写带假设断言的测试。 + +## 步骤 + +### 1. 明确领域术语 +- 若功能名含糊,先用一句话和用户确认它的**统一语言**术语(聚合根、关键值对象、状态)。 +- 参照 `ddd.md` 的建模规约:按意图建模,不按 CRUD。 + +### 2. 加载相关规则 +开工前先读,确保结构不偏离: +- `ddd.md`、`design-discipline.md`、`architecture.md`(分层与依赖方向) +- `error-codes.md`(新错误码先登记) +{%- if include_backend or include_agent %} +- `communication-protocol.md` / `communication-catalog.md`(若涉及跨服务消息) +{%- endif %} + +### 3. 按层生成(依赖恒向内) +只生成本功能需要的层,每层一个文件骨架。**每个方法/函数:写完整签名 + docstring(注明前置/后置条件/不变量),方法体留 `raise NotImplementedError`。** +{% if include_backend %} +**backend/**(见 `backend.md`、`backend-db.md`): +1. `domain/` — 实体/聚合根类(字段 + 意图方法签名)、值对象、`ports.py` 端口 Protocol +2. `application/services/` — service 类骨架,依赖端口(构造注入) +3. `infrastructure/db/` — ORM 映射 + repository 类(实现端口,方法体 TODO) +4. `routers/` — 路由函数签名 + 依赖声明,体内 TODO +5. `core/deps.py` — 依赖注入装配;`main.py` 挂路由 +{%- endif %} +{% if include_agent %} +**agent/**(见 `agent.md`、`agent-dag.md`、`agent-extension-points.md`): +1. `domain/` — 状态聚合、端口 Protocol、异常类 +2. `dag/nodes.py` + `runner.py` — 节点函数签名 + 串联结构,体内 TODO +3. 新外部能力 → 扩展点目录 + 端口 + registry 占位 +{%- endif %} +{% if include_frontend %} +**frontend/**(见 `frontend.md`、`frontend-runtime.md`): +1. `types/` + `schemas/` — 类型定义 + Zod schema(这两层是声明,可写完整) +2. `store/` — Zustand store 结构(state 形状 + action 签名,体内 TODO) +3. `hooks/` — hook 签名 + 返回类型,体内 TODO +4. `components/`(props 接口 + 占位渲染)+ `pages/`(组合骨架) +{%- endif %} + +### 4. 结构自检(只验证骨架能编译,不跑测试) +{%- if include_backend %} +- backend:`cd backend && uv run ruff check src && uv run mypy src` +{%- endif %} +{%- if include_agent %} +- agent:`cd agent && uv run ruff check src && uv run mypy src` +{%- endif %} +{%- if include_frontend %} +- frontend:`cd frontend && pnpm lint && pnpm typecheck` +{%- endif %} + +> 不跑 pytest/vitest——此阶段无业务逻辑,无测试。门禁只确认结构能编译、类型签名自洽。 + +### 5. 汇报 +列出新增/修改的文件、新登记的错误码、以及**留给开发者填充的 TODO 清单**(哪些方法待实现)。 + +## 约束(违反即返工) +- **只搭结构与契约,不猜业务逻辑**——方法体 `raise NotImplementedError`,不臆造算法/规则/测试断言 +- 依赖只能向内:`routers → services → domain.ports ← repositories`,下层绝不 import 上层 +- 实现端口必须显式继承 Protocol + `@override`(见 `design-discipline.md`) +- 不做超前设计,只生成本功能的最小切片;不一次性铺所有目录 +- 新错误码先登记到 `error-codes.md` 再使用 +- 后续填充逻辑时遵循 `testing-tdd.md`:先写测试(Red)再实现(Green)