leikegeek/coding

编码实施

核心原则

1. 严格遵循需求与方案：所有实现必须基于用户确认的需求或设计方案执行；若信息模糊，需先澄清。
2. 编码规范遵从：严格遵循项目既定的编码风格、命名、格式和工程结构。
3. 最小实现 + 精准变更：只实现被要求的功能，只改必须改的代码。详细约束见 coding-discipline 规则。
4. 复用优先：优先复用现有模式、组件和结构，不轻易新造抽象。
5. 风险意识：实现后主动检查兼容性、异常处理和潜在影响。
6. 需求编号关联：所有 commit message 必须关联需求编号。
7. 变更即记录：每次 commit 后同步更新变更记录文档，确保文档与代码始终一致。

TDD 工作节奏

每个任务严格遵循 Red-Green-Refactor-Commit-Record-Progress 节奏：

1. Red：写单元测试，运行确认失败
2. Green：写最小实现代码，运行确认通过
3. Refactor：清理代码（如有必要）
4. Commit：提交，commit message 格式 feat(SV-xxxxx): 简短描述
5. Record：更新变更记录文档（见下方"增量变更记录"）
6. Progress：更新技术方案文档（docs/design/SV-xxxxx-tech-design.md）中的「实施进度」段落，勾选已完成的任务项，更新最后更新时间

Record 是硬门禁：每个任务完成点必须留下变更记录。未完成 Record 和 Progress 前，不得进入下一个任务、不得进入 B3、不得向用户报告“编码完成”。

如果当前流程没有形成 commit（例如用户要求暂不提交、仓库策略禁止提交、子代理返回无 commit hash），仍必须以“任务完成点”为单位记录变更：列出实际变更文件、变更类型、功能说明、测试结果和未提交原因。后续 commit 产生后再补充 commit hash。

增量变更记录

每次 commit 后，立即将本次变更追加到 docs/delivery/SV-xxxxx-changelist.md。

为什么在编码时记录

• 此刻 AI 对变更的理解最准确——刚写完代码，上下文完整
• 避免事后回溯重建，节省 token 消耗
• 为后续统一审计阶段提供可追溯的变更事实和实现依据

每条记录包含

#### T-xxx: {任务描述}

| 文件 | 变更类型 | 说明 |
|------|----------|------|
| path/to/entry-file | 新增 | 功能说明 |
| path/to/related-file | 修改 | 变更说明 |

**接口或契约变更**（如有）：
- `POST /api/xxx` / 组件 props / CLI 参数 — 新增或调整说明

**高风险变更**（如有）：
- `path/to/file#symbol` — 已移除、替换或行为变化说明

高风险变更即时标注

以下变更必须在记录时立即标注为高风险：

• 方法级别的删除（整个方法被移除）
• 代码块被注释掉
• 公共接口签名变更（参数、返回值类型改变）

文档初始化

编码阶段开始时（B1 实施准备完成后），创建变更记录文档骨架：

# 变更清单 SV-xxxxx

> 本文档在编码过程中增量维护，每次 commit 后同步更新。

## 变更记录

（编码过程中逐条追加）

## 需关注：高风险变更

（编码过程中发现高风险变更时追加）

工作流程

1. 先确认需求、边界和成功标准
2. 阅读相关代码，优先复用现有模式和结构
3. 对复杂任务先给出简短实施计划，再开始修改
4. 按 TDD 节奏实现（含第 5 步 Record）
5. 执行 Record 门禁：确认 changelist.md 已覆盖本任务变更，实施进度已更新
6. 实现后自查正确性、兼容性、异常处理和可读性
7. 总结修改点、风险点和建议验证方式

作者配置使用

编码阶段如需生成作者注释，读取全局用户配置：

~/.cursor/coding-exoskeleton/user-config.json

读取规则：

1. 优先使用 author.javaDocAuthor
2. 缺失时使用 author.name
3. 仍缺失时使用 git config --global user.name
4. 仍为空时不生成作者注释，不向项目文件写入占位符

使用边界：

• 仅在新增顶层文件/类且项目现有风格要求作者注释时生成，如 Java @author
• 修改已有文件时，不新增、不改写已有作者注释
• 作者配置不得写入 AGENTS.md、技术方案、变更清单、技术参考文档或 .cursor/harness-config.json
• commit message 默认不追加作者说明；仅当全局配置 author.commitTrailer = true 且团队规范要求时，才追加作者 trailer

编排模式与子代理执行

B2 阶段根据任务复杂度分为两种执行模式（判定逻辑见 code.md B2.0）。

编排模式：主 Agent 职责

当编码任务按业务边界归组后分组数 >= 2 时进入编排模式，主 Agent 的角色转为编排者：

• 基础设施先行：主 Agent 先直接执行所有基础设施任务（项目搭建、数据库迁移、配置初始化等），为编码子代理建立可工作的代码基座
• 拆分：在 B1 阶段完成任务分类（基础设施/编码）、编码任务的业务边界归组（读取 implementation-planning skill）
• 派发：按确认的派发顺序，逐组串行委派子代理执行编码任务；每一时刻只跑一组编码子代理，禁止在用户未明确确认「允许并行」前同时派发多组。为每组准备最小信息集，遵循 coding-subagent agent 的上下文边界（见 commands/code.md B2.0 / B2.2）
• 验收：每组子代理完成后，审核返回结果：
  • 检查每个任务的完成状态
  • 审核子代理自行做出的假设决策是否合理
  • 确认测试全部通过
  • 确认变更在任务范围内
• 收敛：所有组完成后，合并变更记录到 changelist.md、更新实施进度、运行集成验证

编排模式下的强制约束：

• 主 Agent 禁止直接编写业务代码（基础设施任务除外），职责限定为拆分、派发、验收、收敛
• 如果子代理失败需要主 Agent 接管，必须显式退出编排模式并向用户说明原因
• 每组验收通过后再派发下一组（默认串行），前序组的接口契约传递给后续组
• 每组验收通过后必须先合并该组变更记录并更新实施进度；合并失败或记录不完整时，必须重派或补齐，不得派发下一组

编排模式：子代理执行职责

编码子代理在隔离的上下文中执行一组任务（详细定义见 coding-subagent agent 文件）：

• 组内多个任务按依赖顺序串行执行
• 每个任务遵循完整的 TDD + Record 节奏（Red → Green → Refactor → Commit → Record）
• 不直接写入 docs/delivery/SV-xxxxx-changelist.md——变更记录随结果返回，由主 Agent 汇总
• 不更新技术方案文档中的「实施进度」段落——由主 Agent 统一更新
• Record 步骤改为：将变更记录保存为结构化数据（遵循"增量变更记录"中的格式），随任务结果一起返回
• Progress 步骤改为：将任务完成状态随结果一起返回
• 遇到技术方案未覆盖的细节时：业务规则、数据口径、权限/安全、接口契约、兼容迁移等关键缺口必须返回主 Agent 澄清；仅不改变业务语义的局部实现细节可记录假设并继续
• 完成后返回：修改的文件列表、commit hash、变更记录、测试结果、接口契约、假设决策记录

编排模式：异常处理

• 子代理执行失败：主 Agent 记录失败原因，决策"重新派发同组（附修复指示）"或"退出编排模式、主 Agent 接管剩余任务"
• 退出编排模式：必须向用户说明原因。接管意味着编码细节将进入主 Agent 上下文，需评估上下文容量
• 假设决策不合理：主 Agent 标记问题，决策"要求子代理重做相关任务"或"主 Agent 在收敛阶段修复"

直接执行模式（编码任务分组数 < 2）

编码任务不多或仅涉及单一业务模块时，主 Agent 自行编码，流程与 TDD 工作节奏一致，每个任务完成点直接更新 changelist.md 和实施进度；若有 commit，则同步记录 commit hash。

输出约定

• 小任务：输出修改点、风险点、验证建议
• 中型任务：输出实施计划、修改摘要、验证结果
• 大任务：如用户需要，再整理为正式 markdown 文档
• 所有任务：变更记录文档始终保持更新

交互规则

• 若需求或方案不明确，先提问澄清
• 若项目已有明确规范，以项目规范优先
• 小型任务不强制走完整审查或文档流程，优先快速、准确交付
• 复杂任务再提升审查和验证强度