代码实现

实现输入

L2 编码以三份已确认文档为直接依据：

01.需求分析.md
02.技术实现方案.md
03.冒烟与逻辑验证.md

确认需求版本、代码基线、开发工程和真实开发工作区。不得误在 management/.../code/ 分析副本中开发。

Agent 可以使用 git status、git diff、git log 等只读命令调查和 Review，但禁止执行 git add、git commit、git push。暂存、提交和推送均由用户完成；其他可能改变分支或历史的操作必须符合用户指示和安全规则。

项目规范优先

编码前调查：

AGENTS.md、CLAUDE.md 等 Agent 指令；
README.md、CONTRIBUTING.md 和架构文档；
.editorconfig、格式化、Lint、静态分析和构建配置；
测试规范；
当前模块和相邻同类代码。

作用域更近的项目规则优先。没有书面规范时，从同一模块的同类近期实现中提炼惯例，不得凭单个偶然文件确定全局风格。

保持目录、分层、命名、DTO/VO/Entity 划分、校验、异常、错误码、日志、权限、事务、数据访问、Redis、ES、消息、配置、依赖注入、注释和测试风格一致。

保持风格不代表复制明显错误、过时代码或安全缺陷；发现问题时说明并采用最小安全处理。

控制范围

禁止借需求开发进行无关的：

全工程格式化；
大范围重命名；
目录或框架替换；
旧代码全面重构；
注释清洗；
个人偏好的设计模式改造；
不必要的第三方依赖引入。

新增依赖前检查项目已有能力、统一实现、兼容性、构建/部署/安全风险和必要性，并写入方案与实现记录。

敏感信息保护

不在代码、配置、需求文档、日志、测试记录或验证证据中写入密码、Token、Cookie、私钥、访问密钥和完整连接串。
手机号、身份证、地址、客户数据和其他生产敏感信息必须脱敏。
接口请求响应、数据库结果、日志和截图只保留验证所需字段。
凭据通过项目认可的安全环境注入；缺少凭据时请求用户处理，不得创建或保存临时明文凭据。
发现疑似密钥或生产敏感数据进入改动时，立即停止受影响工作并报告。

实施顺序

检查工作区、分支、Commit 和用户已有改动
→ 读取项目规范
→ 确认开发基线
→ 按功能点和工程依赖实施
→ 编写/更新自动化测试
→ 构建和测试
→ 对照冒烟用例自测
→ 更新实现记录和 STATUS

多工程通常按照：

数据脚本与公共模型
→ 服务提供方
→ 服务调用方
→ 消息消费者
→ 前端或外部接入方
→ 联调

实际顺序以已确认方案为准。

TDD

适合自动化的功能执行：

建立失败测试
→ 确认因目标能力缺失而失败
→ 最小实现
→ 测试通过
→ 重构
→ 相关回归

缺陷修复优先建立可复现问题的测试。外部环境导致无法标准测试先行时，记录原因并使用可执行替代验证。

不得通过删除测试、弱化断言、跳过必要用例、吞异常或修改测试迎合错误实现来制造通过。

方案偏差

编码中发现方案不可行时：

记录问题
→ 判断需求和影响
→ 更新 02
→ 更新 03
→ 必要时重开门禁
→ 继续实现

接口契约、数据模型、涉及工程、业务流程、状态、权限、兼容性或需求范围变化时，必须先更新方案。仅私有结构调整且不改变这些内容时，写入实现记录即可。

`04.技术实现记录.md`

记录实现事实，不复制整份方案：

# ST-XXX 技术实现记录

## 1. 实现信息
- 需求版本：
- 技术方案版本：
- 开发工程：
- 开发分支：
- 实现前 Commit：
- 实现后 Commit：
- 当前状态：

## 2. 功能实现状态
| 功能编号 | 功能名称 | 涉及工程 | 实现状态 | 方案章节 | 备注 |
|---|---|---|---|---|---|

## 3. 工程及代码改动
## 4. 数据模型改动
## 5. 接口改动
## 6. 自动化测试改动
## 7. 与技术方案的差异
## 8. 编译和测试结果
## 9. 项目规范遵循情况
## 10. 遗留问题及风险

项目规范遵循情况应列出已读取规范、参考实现、执行的格式/静态检查、差异和原因。

4.4 KiB Raw Permalink Blame History Unescape Escape