146 lines
4.4 KiB
Markdown
146 lines
4.4 KiB
Markdown
# 代码实现
|
||
|
||
## 实现输入
|
||
|
||
L2 编码以三份已确认文档为直接依据：
|
||
|
||
```text
|
||
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、私钥、访问密钥和完整连接串。
|
||
- 手机号、身份证、地址、客户数据和其他生产敏感信息必须脱敏。
|
||
- 接口请求响应、数据库结果、日志和截图只保留验证所需字段。
|
||
- 凭据通过项目认可的安全环境注入；缺少凭据时请求用户处理，不得创建或保存临时明文凭据。
|
||
- 发现疑似密钥或生产敏感数据进入改动时，立即停止受影响工作并报告。
|
||
|
||
## 实施顺序
|
||
|
||
```text
|
||
检查工作区、分支、Commit 和用户已有改动
|
||
→ 读取项目规范
|
||
→ 确认开发基线
|
||
→ 按功能点和工程依赖实施
|
||
→ 编写/更新自动化测试
|
||
→ 构建和测试
|
||
→ 对照冒烟用例自测
|
||
→ 更新实现记录和 STATUS
|
||
```
|
||
|
||
多工程通常按照：
|
||
|
||
```text
|
||
数据脚本与公共模型
|
||
→ 服务提供方
|
||
→ 服务调用方
|
||
→ 消息消费者
|
||
→ 前端或外部接入方
|
||
→ 联调
|
||
```
|
||
|
||
实际顺序以已确认方案为准。
|
||
|
||
## TDD
|
||
|
||
适合自动化的功能执行：
|
||
|
||
```text
|
||
建立失败测试
|
||
→ 确认因目标能力缺失而失败
|
||
→ 最小实现
|
||
→ 测试通过
|
||
→ 重构
|
||
→ 相关回归
|
||
```
|
||
|
||
缺陷修复优先建立可复现问题的测试。外部环境导致无法标准测试先行时，记录原因并使用可执行替代验证。
|
||
|
||
不得通过删除测试、弱化断言、跳过必要用例、吞异常或修改测试迎合错误实现来制造通过。
|
||
|
||
## 方案偏差
|
||
|
||
编码中发现方案不可行时：
|
||
|
||
```text
|
||
记录问题
|
||
→ 判断需求和影响
|
||
→ 更新 02
|
||
→ 更新 03
|
||
→ 必要时重开门禁
|
||
→ 继续实现
|
||
```
|
||
|
||
接口契约、数据模型、涉及工程、业务流程、状态、权限、兼容性或需求范围变化时，必须先更新方案。仅私有结构调整且不改变这些内容时，写入实现记录即可。
|
||
|
||
## `04.技术实现记录.md`
|
||
|
||
记录实现事实，不复制整份方案：
|
||
|
||
```markdown
|
||
# ST-XXX 技术实现记录
|
||
|
||
## 1. 实现信息
|
||
- 需求版本：
|
||
- 技术方案版本：
|
||
- 开发工程：
|
||
- 开发分支：
|
||
- 实现前 Commit：
|
||
- 实现后 Commit：
|
||
- 当前状态：
|
||
|
||
## 2. 功能实现状态
|
||
| 功能编号 | 功能名称 | 涉及工程 | 实现状态 | 方案章节 | 备注 |
|
||
|---|---|---|---|---|---|
|
||
|
||
## 3. 工程及代码改动
|
||
## 4. 数据模型改动
|
||
## 5. 接口改动
|
||
## 6. 自动化测试改动
|
||
## 7. 与技术方案的差异
|
||
## 8. 编译和测试结果
|
||
## 9. 项目规范遵循情况
|
||
## 10. 遗留问题及风险
|
||
```
|
||
|
||
项目规范遵循情况应列出已读取规范、参考实现、执行的格式/静态检查、差异和原因。
|
||
|
||
实现完成仅表示代码准备进入 Review，不等于子任务最终完成。
|