# 代码生成

## 输入要求

1. **功能需求**（必填）：需要实现的功能描述
2. **编程语言**（必填）：如Python、JavaScript、Go、Java
3. **框架/库**（可选）：如React、Spring Boot、FastAPI
4. **约束条件**（可选）：如"时间复杂度O(n)"、"不使用第三方库"
5. **输入输出示例**（可选）：期望的输入和输出格式

## 执行流程

### 第〇步：TDD 与审查链前置决策（复杂任务）

当意图三分法判定为「复杂任务」（多文件/跨模块/数据持久化/安全敏感），在执行 Spec 检查前，先做出以下链式决策：

**决策规则**：

| 条件                               | 动作                                                 |
| ---------------------------------- | ---------------------------------------------------- |
| 任务涉及 ≥ 2 个模块联动            | 生成后自动联动 `test-generation`（至少覆盖集成路径） |
| 任务涉数据持久化/网络通信/安全敏感 | 生成后自动联动 `code-review`（完整深度审查）         |
| 代码预计超过 200 行                | 以上两项同时联动                                     |
| 单函数/单文件/纯计算               | 跳过本步骤，进入第一步 Spec 检查                     |

**输出格式**：

```
✓ TDD+审查链: [联动 test-generation] / [联动 code-review] / [同时联动] / [跳过]
```

本决策在执行前确定，不等到第六步再判断，避免遗漏验证链。

### 第一步：Spec检查

编码前检查是否有明确的spec：

- **如有spec**：提取spec中的scenario作为编码验收依据，严格按Given/When/Then实现
- **如无spec**：提示用户先使用 `spec-driven-development` 对齐需求，或生成轻量级spec

```
✓ Spec检查: [检测到/未检测到] 需求规格
[如检测到，列出相关scenario]
```

### 第二步：编码前环境确认

生成代码前，先确认环境和依赖：

- 确认目标编程语言和版本
- 确认依赖库和框架版本
- 确认运行环境约束（操作系统、内存、网络等）

**示例**：

```
环境确认：Python 3.10+，无第三方依赖，单文件运行。
```

### 第三步：需求分析

- 理解功能需求和业务场景
- 识别核心算法或设计模式
- 明确约束条件（性能、兼容性、依赖）
- 明确陈述假设：如果需求有歧义，列出多种理解并选择最简方案
- **Karpathy约束**：识别并排除超出需求的功能；如果存在更简单的方案，优先选择简单方案
- **加载项目规范 + 强制风格嗅探**：从项目记忆中加载相关编码规范（命名约定、错误处理模式等）；并在生成/修改前按 `style-alignment.md` 协议**先读取目标项目已有的代表性文件**，提取缩进/开标签/括号位置/数组键引号/模板变量命名等风格标记，产出「风格基线」块，生成代码逐行对齐——**禁止凭 Agent 自身想象套用风格**（二开/插件开发/修改现有文件场景强制；Trivial Fix 改现有文件同样适用）

### 第四步：设计方案

- 确定函数/类/模块的接口
- 设计数据结构
- 规划错误处理策略
- **Karpathy约束**：最小设计，不预先为"未来可能"做抽象

### 第五步：代码实现（Simplicity First）

生成包含以下要素的代码：

- 清晰的函数/类签名
- 输入验证和参数检查
- 核心逻辑实现（最少代码解决问题）
- 错误处理（只处理可能发生的场景）
- 边界条件处理（空值、越界、超时）
- **简洁优先**（Karpathy原则）：选择最简单的实现方式

**Karpathy约束**：

- 不要超出需求的功能
- 不要为单次使用代码做抽象
- 不要未被要求的"灵活性"或"可配置性"
- 不要为不可能场景做错误处理
- 如果200行可以50行搞定，重写

### 第五步点五：NFR 决策（非功能需求）

生成代码须对非功能需求（NFR）做**显式决策**，逐项判定以下维度（禁止留白）：

| NFR 维度  | 必须回答                               | 默认处理                                       |
| --------- | -------------------------------------- | ---------------------------------------------- |
| 并发/竞态 | 是否存在共享可变状态？并发写是否可能？ | 无共享态则标注"无竞态"；有则给锁/原子/幂等方案 |
| 幂等      | 写操作重复调用是否产生副作用？         | 非幂等须定义幂等键或唯一约束                   |
| 重试/超时 | 外部调用是否有超时上限？失败是否重试？ | 必须设超时上限；重试须幂等且有退避             |
| 降级      | 依赖不可用时的行为是什么？             | 降级路径须明确（缓存兜底/默认值/失败提示）     |
| 容量/规模 | 数据量增长到 N 时是否仍正确可运行？    | 列表须分页/游标，禁无界拉取                    |
| 可观测性  | 关键路径是否有日志/指标/追踪？         | 关键决策与错误须有日志，禁静默吞异常           |
| 安全      | 外部输入是否校验？输出是否转义？       | 遵循 `execution-safety.md` 安全红线清单        |

**判定规则**：

- 命中复杂度门槛（多候选/跨模块/高影响）→ 先走 `architecture-decision` 产出决策记录，再编码
- 单项标注"无需处理"须写明理由，禁止留白
- 输出格式中补「非功能需求设计」章节（见下）

### 第六步：代码审查

**审查路由规则**：

- **内联精简审查**（本步骤）：适用于单函数/单文件、功能边界清晰、无外部依赖的代码生成，执行以下四项基本检查。
- **完整深度审查**（走 `code-review.md` 完整流程）：适用于多文件/多模块联动、涉及数据持久化/网络通信/安全敏感操作，或代码超过 200 行时，触发 8 步完整审查流程（Spec 一致性→项目规范→代码理解→多维度审查→Karpathy 维度→问题分级→修复建议→记录到项目记忆）。

**内联审查项**：

- 检查代码逻辑是否正确
- 确认是否有更好的实现方式
- 验证边界条件处理
- **精准修改**（Karpathy原则）：只修改必要部分，不引入无关变更

**证据格式（必填，对齐主流程 Step 4）**：

| 审查类型     | 证据类型  | 最小字段                                       |
| ------------ | --------- | ---------------------------------------------- |
| 内联精简审查 | 命令+输出 | lint 命令 + 退出码 + 问题清单                  |
| 完整深度审查 | 命令+输出 | 审查报告 + 问题分级清单（阻塞/严重/一般/建议） |
| 边界条件验证 | 测试报告  | 测试用例数、通过数、失败用例清单               |

未声明证据类型的验证视为未完成。

### 第七步：补充说明（Goal-Driven）

- 使用示例
- 复杂度分析
- 注意事项
- **成功标准**：说明如何验证这段代码正确工作

### 第八步：记录到项目记忆

代码生成完成后，将关键决策和新发现的规范记录到项目记忆（参见 `project-memory-management.md`）：

- 记录实现中的关键技术选择（Decision Record 模式）：如算法选型、依赖库选择、错误处理策略
- 记录新发现的编码规范（Convention Capture 模式）：如命名约定、目录组织、模块划分
- 若生成过程中暴露需求歧义，反馈到 spec 或更新规范防止下次重蹈

## Task Summary: 代码生成

```
**完成状态**: [完成/部分完成]
**生成文件**: [文件列表]
**关键决策**: [实现中做出的技术选择]
**偏差说明**: [与原始需求的差异及原因]
**验证建议**: [如何验证这段代码]
```

## 输出格式

````markdown
# [功能名称]

## 代码实现

```[语言]
[完整可运行的代码，含必要的 import / package 声明]
```

## 使用示例

```[语言]
// 示例输入（以下以 JavaScript 为例）
const result = functionName(input);
console.log(result);
// 示例输出
// { "key": "value" }
```

## 复杂度分析

- **时间复杂度**：[O(X)]，[一句话说明瓶颈操作]
- **空间复杂度**：[O(X)]，[一句话说明额外空间来源]

## 设计说明

[为什么选择这种实现方式，而非备选方案。如有 trade-off 需明确说明。]

## 非功能需求设计

| 维度      | 决策                        | 理由                            |
| --------- | --------------------------- | ------------------------------- |
| 并发/竞态 | [无竞态 / 锁 / 原子 / 幂等] | [一句话]                        |
| 幂等      | [是 / 否]                   | [幂等键/唯一约束或说明为何不需] |
| 重试/超时 | [上限值 + 退避策略]         | [外部依赖说明]                  |
| 降级      | [降级路径]                  | [触发条件]                      |
| 容量/规模 | [分页/游标/流式]            | [预估规模]                      |
| 可观测性  | [日志/指标/追踪]            | [关键路径]                      |

## 边界条件处理

| 边界条件          | 处理方式                      |
| ----------------- | ----------------------------- |
| 空输入            | [返回空/抛异常/默认值]        |
| 超大输入（n > ?） | [分页/流式/降级]              |
| 非法参数类型      | [抛 IllegalArgumentException] |
| 并发/重入         | [锁/无状态/幂等]              |

## 依赖项

- [第三方库名称] v[X.Y.Z]：[用途说明]
- **锁文件要求**：项目必须基于 `composer.lock` / `package-lock.json` / `pnpm-lock.yaml` 锁文件安装依赖，禁止使用 `latest` / `*` / `dev-main` 浮动版本；新增依赖时同步更新锁文件

## 注意事项

1. [注意事项1：如特定环境限制]
2. [注意事项2：如已知局限性]
3. [注意事项3：如后续优化方向]
````

## 实战请求示例

下面示例用于指导用户把需求说清楚，避免只给一句“帮我写个功能”导致反复澄清。

### 示例一：后台列表接口

```text
帮我实现一个订单列表接口。
语言/框架：PHP 8.2，Laravel 10。
输入：page、page_size、status、keyword。
输出：订单列表、总数、分页信息。
约束：page_size 最大 100；keyword 搜索订单号和手机号；所有外部输入必须校验；SQL 不能拼接。
验证：给出 Feature Test，覆盖正常分页、非法 page_size、keyword 模糊搜索。
```

生成时应优先加载：`laravel-development.md`、`mysql-database.md`、`test-generation.md`。

### 示例二：CMS 批量任务

```text
帮我给帝国CMS后台做一个批量刷新文章缓存功能。
环境：EmpireCMS 7.5，PHP 8.2。
要求：不能单请求跑完，必须 Init-Step-Poll；每批 50 条；前端显示进度、失败数和重试按钮。
安全：后台权限校验、CSRF 校验、输出转义。
验证：给出 Init、Step、Poll 的响应示例和手动测试步骤。
```

生成时应优先加载：`cms-development.md`、`api-design.md`、`frontend-design.md`；进入验证设计时再切换到 `test-generation.md`，避免一次加载超过 3 个 reference。

### 示例三：小工具脚本

```text
帮我写一个 Python 脚本，扫描目录下所有 .md 文件，统计标题数量和断链数量。
约束：Python 3.10+，只读文件，不修改；跳过 node_modules、vendor、.git。
输出：表格形式打印文件、标题数、断链数；退出码 0 表示无断链，1 表示存在断链。
验证：给出最小样例目录和运行命令。
```

生成时应优先加载：`code-generation.md`，如涉及性能再协同 `performance-benchmark.md`。

## 质量标准

- 生成的代码必须可直接运行，不能是伪代码
- 必须处理常见的边界条件（空输入、越界、类型错误）
- 必须包含错误处理，不能假设输入总是合法
- 变量和函数命名必须符合语言惯例（如Python用snake_case，JS用camelCase）
- 复杂逻辑必须添加注释说明
- 不得生成包含安全漏洞的代码（如SQL拼接、eval执行用户输入）
- **Karpathy红线**：不得为单一需求生成抽象类、接口、配置对象等过度设计
- 涉及 MySQL/SQL/表结构/索引/事务时，必须先参考 `mysql-database.md`，再生成代码

## CMS 二次开发注意事项

当目标为 PHP+MySQL CMS 二次开发时，额外遵守：

1. **数据访问层**：必须使用 CMS 官方 API（WP: `$wpdb` / TP: `Db` / Laravel: Eloquent / ECMS: `$empire->query()`），禁止原生 `mysqli_*`
2. **SQL 安全**：条件必须参数绑定，LIKE 用 `CONCAT('%', ?, '%')`，禁止 `$_GET/$_POST` 直拼
3. **输出转义**：`htmlspecialchars(..., ENT_QUOTES, 'UTF-8')` 或 CMS 等效函数，模板引擎输出默认转义
4. **金额字段**：DECIMAL → PHP `string`，禁止 `float`，防止精度丢失
5. **插件标准**：一功能一文件，命名 `action_module_function.php`，单一入口
6. **PHP 兼容性**：数组键加引号 `$arr['key']`，禁止 `each()`/`create_function()`/`mysql_*`，`===` 替代 `==`

详见 `cms-development.md`。

## 关联 reference

- **karpathy-coding-guidelines**（Karpathy编码规范）— 生成后可用 `karpathy-coding-guidelines` 检查是否符合编码哲学
- **frontend-design**（前端设计）— 生成页面/组件前先用 `frontend-design` 确定信息架构、视觉规范、交互状态和响应式策略
- **code-review**（代码审查）— 生成后可用 `code-review` 检查代码质量
- **test-generation**（测试用例生成）— 生成后可用 `test-generation` 生成配套测试
- **doc-generation**（文档生成）— 生成后可用 `doc-generation` 生成函数文档
- **cms-development**（CMS二次开发）— PHP+MySQL CMS 场景参考 `cms-development.md` 的数据访问层和安全规范
- **mysql-database**（MySQL数据库）— 涉及表结构、SQL、索引、事务、慢查询和迁移时参考 `mysql-database.md`
- **architecture-decision**（架构决策）— 生成前命中复杂度门槛（多候选/跨模块/高影响）时，先走架构决策流程产出决策记录
- **project-memory-management**（项目记忆管理）— 记录实现中的关键技术选择和新发现的编码规范

## 失败回退机制

| 步骤                                 | 失败条件                           | 回退目标                               | 最大重试 | 不可恢复时升级路径                                 |
| ------------------------------------ | ---------------------------------- | -------------------------------------- | -------- | -------------------------------------------------- |
| 第一步：Spec检查                     | 无关联spec/文件/用户上下文         | 直接基于用户描述启动，标注"无spec对照" | 0        | 提示用户先走 Spec驱动开发 对齐需求，或手动描述需求 |
| 第二步：编码前环境确认               | 目标语言/版本无法确认              | 使用当前环境默认设置，标注假设         | 1        | 提示用户明确指定语言和版本                         |
| 第三步：需求分析                     | 需求存在不可调和的歧义             | 列出歧义点，要求用户澄清               | 0        | 选择最简方案并标注"假设"，由用户后续修正           |
| 第四步：设计方案                     | 设计约束冲突（性能vs简洁不可兼得） | 优先简洁方案，标注性能取舍             | 2        | 提供两套方案供用户选择                             |
| 第五步：代码实现（Simplicity First） | 依赖库不可用或版本不兼容           | 降级到标准库实现或标注兼容性说明       | 2        | 输出伪代码框架+待替换标注，移交人工实现            |
| 第六步：代码审查                     | 内联审查发现逻辑缺陷               | 退回第四步重新设计方案                 | 2        | 触发 code-review.md 完整审查流程                   |
| 第七步：补充说明（Goal-Driven）      | 成功标准无法量化或验证方法不可行   | 提供定性验证建议，标注"待量化"         | 2        | 输出验证骨架，建议用户补充具体验收条件             |
| 第八步：记录到项目记忆               | 项目记忆系统不可用                 | 输出Decision Record到本地文件          | 1        | 标注"决策未沉淀"，提示用户手动保存                 |