fmode-app/.claude/skills/dev-expert/references/code-generation.md

代码生成

输入要求

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: 代码生成

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

输出格式

# [功能名称]

## 代码实现

```[语言]
[完整可运行的代码，含必要的 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：如后续优化方向]

实战请求示例

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

示例一：后台列表接口

帮我实现一个订单列表接口。
语言/框架：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 批量任务

帮我给帝国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。

示例三：小工具脚本

帮我写一个 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	标注"决策未沉淀"，提示用户手动保存