【Claude Code】和【codex】的提示词编程工程 的文件内容结构和这些提示词文件的目录结构 在做AI编程规范化的时候都是怎么设计的，从需求确立——技术细分 ——数据建模—接口设计—代码生成 — 测试单元生成
为了方便你记忆并能在大型企业真正落地，我们将这两套体系完全拆开。
在大型企业中，【Claude Code 体系】 适合用于打造基于 CLI（命令行）或 Agent 管道的全自动全流程无人值守流水线；而 【Codex 体系】 适合用于打造基于 IDE 插件（如 Cursor、VS Code 扩展）的人机协同智能工作空间。
以下是针对这两种体系，从需求到测试全链路（1 $\rightarrow$ 6 阶段）设计的详细文件结构及注释：
体系一：【Claude Code 体系】—— 路径感知与 Agent 自动化流水线
Claude Code 的核心是“路径感知 (Path-Scoped)”与“原生命令行能力 (CLI Skills)”。它通过 rules 动态控制 AI 在不同目录下的思维模式，通过 skills 赋予 AI 在终端执行重构、编译、测试的实际行动力。
Plaintext
my-enterprise-project/
├── CLAUDE.md # 项目最高统领文件：配置技术栈、核心构建与测试命令、顶层规范
└── .claude/ # Claude Code 官方标准配置根目录
├── rules/ # 【静态约束层】—— 利用 Frontmatter 的 paths 实现按需加载
│ ├── 01_requirement.md # 需求确立：规范 PRD/UserStory 的 Markdown 结构与验收标准(AC)
│ │ # [路径挂载]: paths: ["docs/prd/**/*", "requirements/**/*.md"]
│ ├── 02_architecture.md # 技术细分：定义企业架构分层（DDD/MVC）与原子化任务拆解颗粒度
│ │ # [路径挂载]: paths: ["docs/tasks/**/*", "todo.md"]
│ ├── 03_modeling.md # 数据建模：硬性约束数据库军规（主键 UUID、小写下划线、审计字段）
│ │ # [路径挂载]: paths: ["infra/db/**/*", "**.prisma", "**.sql"]
│ ├── 04_api_design.md # 接口设计：规范 OpenAPI 3.0/Swagger 结构、RESTful 状态码与统一返回体
│ │ # [路径挂载]: paths: ["docs/api/**/*", "src/dtos/**/*"]
│ ├── 05_codegen.md # 代码生成：定义防御性编程习惯、日志埋点（ContextID）与错误处理规范
│ │ # [路径挂载]: paths: ["src/services/**/*", "src/controllers/**/*"]
│ └── 06_testing.md # 测试生成：规范 Mock 策略、单元测试边界条件以及断言工具的使用
│ # [路径挂载]: paths: ["**/*.test.ts", "**/*.spec.js", "tests/**/*"]
│
└── skills/ # 【动态能力层】—— 封装为独立文件夹，供 AI 自动/手动通过 /命令 触发
├── prd-analyzer/
│ └── SKILL.md # 自动化需求分析技能：教导 AI 将模糊对话输入直接生成规范 PRD 并落盘
├── task-splitter/
│ └── SKILL.md # 任务拆解技能：读取 PRD，自动生成具有依赖顺序的本地 Kanban/Todo 文件
├── model-scaffolder/
│ └── SKILL.md # 自动建模技能：读取任务单，自动创写或增量修改本地的 ORM Schema / DDL 文件
├── api-compiler/
│ └── SKILL.md # 接口生成技能：基于 Schema，一键在特定目录派生 DTO 和接口契约定义文件
└── test-automator/
└── SKILL.md # 测试验证闭环技能：AI 自动编写测试，隐式在宿主终端运行 test 命令，
# 捕获报错并自动原地重写修复，直至测试 100% 通过（实现闭环控制）
体系二：【Codex / 现代 IDE 通用体系】—— 上下文基座与人机协同工作区
通用 Codex / IDE 体系（如 Cursor 的 .cursorrules）的核心是“全量上下文注入 (Context-Rich)”与“蓝图模板复用 (Blueprint Templates)”。由于它无法在终端自动运行管道脚本，它需要通过一个大一统的规则文件来洗脑，并依赖一组静态的“工程蓝图（Templates）”引导 AI 在聊天框中产出符合规范的代码。
Plaintext
my-enterprise-project/
├── .cursorrules # 【大一统上下文洗脑文件】——（或叫 .coderules / .codex）
│ # 将 1~6 阶段的研发军规、企业代码风格、接口契约合并写入该单文件。
│ # AI 在左侧/右侧侧边栏聊天、生成代码时，会全程、无条件地遵守此文件内的约束。
│
└── .codex/ # 【企业工程蓝图与模板库】—— 存放供 AI 在生成内容时强行参考/复制的标准模板
├── 01_requirement_template.md # 需求确立：标准 PRD 模板。包含 Actor、User Story、Given-When-Then 验收场景。
│ # [作用]: 约束 AI：“请严格按照此模板的内容结构，将用户的自然语言转化为 PRD。”
├── 02_architecture_blueprint.md # 技术细分：系统架构图定义。规定项目的包目录结构、模块依赖红线、中间件限制。
│ # [作用]: 约束 AI：“拆解技术任务时，不能超出此架构蓝图划定的技术栈边界。”
├── 03_data_model_template.sql # 数据建模：标准 DDL / Schema 范本。包含标准的索引命名、分区、软删除规范示例。
│ # [作用]: 约束 AI 编写 SQL 时的风格，给 AI 提供一个“完美的对照组”。
├── 04_api_spec_template.json # 接口设计：企业级 OpenAPI / Swagger 规范范本。包含统一错误码（如 ERR_001）的 JSON 结构。
│ # [作用]: 引导 AI 严格遵循面向契约编程（API-First），先出 DTO 再写逻辑。
├── 05_code_style_guide.md # 代码生成：代码风格白皮书。严禁使用的危险函数、异常捕获规范、异步处理规范、Lint 规则。
│ # [作用]: 注入到 AI 的生成逻辑中，确保生成的每一行代码都像出自同一个资深工程师之手。
└── 06_unit_test_template.ts # 测试单元：标准单元测试/集成测试脚手架模板。包含 Mock 外部 RPC、Redis 的标准写法。
# [作用]: AI 编写 `*.spec.ts` 时必须以此文件为基座进行补全，防止其写出无效断言。
💡 记忆与落地心法
为了让你最快地记住这两者的架构设计并用于企业落地，可以总结为两句话：
-
Claude Code 体系是“微服务化”的：
-
它把规则变成了“传感器”（
rules/加上paths拦截，到了对应目录才生效，省 Token）。 -
它把动作变成了“机械臂”（
skills/，AI 可以自己去敲键盘、跑测试、修 Bug）。
-
-
Codex / IDE 体系是“中央集权化”的：
-
它用一个“最高宪法”（
.cursorrules）管住 AI 所有的想法。 -
它用一堆“参考书”（
.codex/里的templates）限制 AI 必须交出相同格式的作业。
-
上述结构每个文件的大致文件内容
为了让这套体系在企业级项目中真正跑通，以下为你将这两套体系（Claude Code 体系 与 Codex / IDE 体系）所有衍生文件的大致内容框架进行规范化设计。
体系一：【Claude Code 体系】全量文件内容设计
1. 项目最高统领：CLAUDE.md
Markdown
# Project Command Center & Guidelines
## 1. Tech Stack
- Backend: NestJS v10 (TypeScript 5.x, Strict Mode)
- ORM: Prisma ORM v5
- Testing: Jest & Supertest
## 2. Core Commands
- Build: `npm run build`
- Lint & Format: `npm run lint` / `npm run format`
- Unit Test: `npm run test:unit`
- Database Migration: `npx prisma migrate dev`
## 3. Architecture Principles
- Follow standard DDD / Clean Architecture.
- Strict layered validation via Class-Validator.
2. 需求确立规则：.claude/rules/01_requirement.md
Markdown
---
description: Rules for analyzing requirements and generating formal PRD documentation
paths: ["docs/prd/**/*", "requirements/**/*.md"]
---
# 研发军规：需求确立规范
1. **统一语言**：必须使用业务通用语言，避免含糊其辞的词汇（如“系统要快”）。
2. **结构红线**：所有 PRD 必须包含 `User Story` 矩阵与 `Acceptance Criteria (AC)`。
3. **AC 语法格式**：每个功能点的验收标准必须严格按照 BDD 的形式编写：
- **Given**（在什么业务前提下）
- **When**（执行了什么操作）
- **Then**（预期产生什么结果）
3. 技术细分规则：.claude/rules/02_architecture.md
Markdown
---
description: Enforces architecture compliance and atomic task engineering
paths: ["docs/tasks/**/*", "todo.md"]
---
# 研发军规：技术细分与架构规范
1. **分层架构红线**：代码严格划分为 `Controller`（看门人）、`Service`（业务逻辑）、`Repository/Prisma`（数据访问）、`DTO/VO`（协议数据）。严禁层级越权。
2. **原子化任务拆解**：在拆解开发任务时，单个 Task 的颗粒度不得超过 4 个工时。
3. **依赖强绑定**：生成的任务链必须标明前置依赖（例如：必须先输出模型 DTO，才能开始 Service 实现）。
4. 数据建模规则：.claude/rules/03_modeling.md
(参考上一次为你生成的完整版本，保持其核心：UUID 主键、小写下划线、复数表名、5大审计字段、禁用物理外键。)
5. 接口设计规则：.claude/rules/04_api_design.md
Markdown
---
description: Enforces OpenAPI specifications and corporate response formats
paths: ["docs/api/**/*", "src/dtos/**/*"]
---
# 研发军规：接口设计规范
1. **RESTful 命名**：资源路由一律使用复数名词。示例：`GET /api/v1/orders`，禁止使用 `GET /api/v1/getOrders`。
2. **统一契约体**：所有响应必须被包裹在统一的 JSON 结构内（包含 `success`, `traceId`, `data`, `error`）。
3. **参数校验**：所有入口 DTO 必须无条件挂载 `class-validator` 装饰器（如 `@IsUUID()`, `@IsNotEmpty()`）。
6. 代码生成规则：.claude/rules/05_codegen.md
Markdown
---
description: Guidelines for robust code generation and logging
paths: ["src/services/**/*", "src/controllers/**/*"]
---
# 研发军规：核心代码生成规范
1. **防御性编程**：任何涉及数据库或第三方 RPC 的 I/O 操作，必须使用 `try-catch` 包裹，防范未捕获异常。
2. **可观测性埋点**：在 `catch` 块中必须调用系统内置的 Logger，且必须显式传入当前请求的 `traceId`，禁止打印空日志。
3. **极简控制器**：Controller 只允许做数据路由、身份鉴权和参数校验，绝对不允许包含任何核心业务逻辑。
7. 测试生成规则：.claude/rules/06_testing.md
Markdown
---
description: Strict rules for unit testing and mock enforcement
paths: ["**/*.test.ts", "**/*.spec.js", "tests/**/*"]
---
# 研发军规：测试单元生成规范
1. **沙箱隔离**：单元测试严禁调用、连接真实数据库或 Redis，所有外部依赖必须通过 Jest 进行 Full Mock。
2. **用例完整性**：针对一个核心方法，AI 至少需要生成 1 个 Happy Path 用例和 2 个以上的异常分支（如空输入、超时、权限拒绝）用例。
3. **生命周期治理**：必须在 `afterEach` 钩子中执行 `jest.clearAllMocks()`，严禁测试用例间的状态污染。
🛠️ Claude Code 动态技能层 (skills/) 内容设计
技能一：.claude/skills/prd-analyzer/SKILL.md
YAML
---
name: prd-analyzer
description: 将用户的模糊指令，结合 01_requirement.md 规范自动格式化输出标准的 PRD
---
# 执行步骤
1. 解析用户给出的初始功能设想。
2. 调阅 `.claude/rules/01_requirement.md` 获取标准。
3. 在 `docs/prd/` 下输出标准的 Markdown 文档并向人类确认。
技能二：.claude/skills/task-splitter/SKILL.md
YAML
---
name: task-splitter
description: 读取现有的标准 PRD 文件，将其进行拆解并生成本地 todo.md 任务链
---
# 执行步骤
1. 打开并解析指定的 PRD 文件。
2. 依据 `02_architecture.md` 规则，将业务转化为 NestJS 分层开发子任务。
3. 在项目根目录下创建或更新 `todo.md`。
技能三：.claude/skills/model-scaffolder/SKILL.md
YAML
---
name: model-scaffolder
description: 基于 todo.md 中的建模任务，自动增量修改 schema.prisma 文件
---
# 执行步骤
1. 定位 `prisma/schema.prisma`。
2. 按照 `03_modeling.md` 的规范，自动编写 Model 模型结构。
3. 在沙箱执行 `npx prisma format` 确保语法绝对正确。
技能四：.claude/skills/api-compiler/SKILL.md
YAML
---
name: api-compiler
description: 扫描最新的 Prisma Schema，自动化生成底层的 DTO 文件和 Controller 签名
---
# 执行步骤
1. 读取新建立的数据模型。
2. 遵循 `04_api_design.md`，在 `src/dtos/` 下生成入参校验类。
3. 在对应的 `*.controller.ts` 中写出空的方法声明。
技能五：.claude/skills/test-automator/SKILL.md
(参考上一次为你生成的完整版本，保持其核心：自动定位测试文件 $\rightarrow$ 终端静默跑测试 <span class="math-inline" data-math="\rightarrow" data-index-in-node="51">$\rightarrow$ 失败捕获报错 <span class="math-inline" data-math="\rightarrow" data-index-in-node="70">$\rightarrow$ 闭环原地自愈修改。)
体系二：【Codex / 现代 IDE 通用体系】全量文件内容设计
1. 大一统上下文洗脑文件：.cursorrules
(参考上一次为你生成的完整版本，保持其核心：全局技术栈注入 $\rightarrow$ 六阶段人机协同生命周期硬性声明 <span class="math-inline" data-math="\rightarrow" data-index-in-node="58">$\rightarrow$ 强行绑定各阶段调用模板的指针。)
2. 需求确立模板：.codex/01_requirement_template.md
Markdown
# 东方科技集团标准 PRD 模板
## 1. 业务背景 (Background)
## 2. 核心参与者 (Actors)
- 角色 A: [描述其系统权限]
- 角色 B: [描述其系统权限]
## 3. 用户故事矩阵 (User Stories)
- [US-01] 作为____, 我希望____, 以便____。
## 4. 验收标准矩阵 (Acceptance Criteria)
### AC-01 [对应故事编号]
- **Given**: ________________
- **When**: ________________
- **Then**: ________________
3. 技术细分蓝图：.codex/02_architecture_blueprint.md
Markdown
# NestJS 标准项目分层蓝图规范
## 1. 标准目录树骨架
src/
├── controllers/ # 路由层：负责 Http 状态码、路由分发、class-validator 参数校验
├── services/ # 业务逻辑层：负责处理核心业务、事务控制、调用 Repository
├── dtos/ # 数据契约层：负责输入/输出实体的结构定义与拦截定义
└── infra/ # 基础设施层：负责数据库连接（Prisma）、Redis、第三方组件挂载
## 2. 依赖红线
- 严禁在 `Controller` 直接写入任何底层 SQL 或 Prisma 链式调用。
- `Service` 之间如需相互调用，禁止产生循环依赖 (Circular Dependency)。
4. 数据建模范本：.codex/03_data_model_template.sql
SQL
-- 东方科技集团标准 DDL 建模范本（AI 生成 SQL/Prisma 时的完美对照组）
CREATE TABLE biz_example_entities (
-- 1. 主键硬性规范
id VARCHAR(36) NOT NULL PRIMARY KEY,
biz_name VARCHAR(100) NOT NULL,
-- 2. 金融/资产字段精度规范
account_balance DECIMAL(18, 4) NOT NULL DEFAULT 0.0000,
-- 3. 五大强制审计字段
created_at TIMESTAMP WITH TIME ZONE NOT NULL DEFAULT CURRENT_TIMESTAMP,
updated_at TIMESTAMP WITH TIME ZONE NOT NULL DEFAULT CURRENT_TIMESTAMP,
created_by VARCHAR(36) NOT NULL,
updated_by VARCHAR(36) NOT NULL,
is_deleted SMALLINT NOT NULL DEFAULT 0
);
CREATE INDEX idx_biz_example_created ON biz_example_entities(created_at);
5. 接口设计标准：.codex/04_api_spec_template.json
(参考上一次为你生成的完整标准 JSON Schema，保持其核心：定义 success, traceId, data, 且 error 严格符合 ERR_模块名_原因 格式。)
6. 代码风格指南：.codex/05_code_style_guide.md
Markdown
# 企业级代码生成风格指南
## 1. 异步处理与并发
- 全局禁止使用原始的 `.then()` / `.catch()` 链式写法，必须且仅能使用 `async/await`。
- 循环中的异步 I/O 严禁使用 `forEach`，必须使用 `for...of` 或 `Promise.all()`。
## 2. 异常控制机制
- 严禁吞掉异常（即 `catch(e) {}` 里面什么都不做）。
- 捕获异常后，如果不需要向上抛出，必须使用以下格式打印：
`this.logger.error(`[${traceId}] 模块名称执行失败, 原因: ${error.message}`, error.stack);`
7. 测试单元脚手架：.codex/06_unit_test_template.ts
(参考上一次为你生成的完整单元测试文件，包含 Mock 数据库隔离原则、clearAllMocks 治理、Happy Path 用例与两个以上的 Exception Path 边界断言。)
💡 落地对比记忆卡片
-
Claude 体系的内容逻辑：每个文件头部都自带“监控雷达（
paths）”。内容多用短小精悍的命令式和红线约束，因为后续有 Skill 脚本帮它进行语法检查、编译和拦截。 -
Codex 体系的内容逻辑：内容充满大量“视觉模板”与“JSON Schema 规范”。它在用高度完备的文档样本，去强行让 IDE 侧边栏的 AI 进行高效的“照葫芦画瓢”（Few-Shot Prompting）。
浙公网安备 33010602011771号