compound-engineering

这项技能实现了复利式工程——一种开发方法，其中每项工作都会让后续工作更轻松，而不是更困难。其灵感来自 Every.to 的工程实践。

核心理念

每项工程工作都应让后续工作更轻松，而不是更困难。

传统开发会累积技术债。每项功能都会增加复杂性。每次改动都会加重维护负担。复利式工程则反其道而行，通过建立一个学习循环，将每个 Bug、测试失败或问题解决经验记录下来，供后续工作使用。

复利式工程循环

Plan → Work → Review → Compound → (repeat)

1. 规划（40%）：研究解决方案，将信息综合整理为详细的实施计划
2. 执行（20%）：系统地执行计划，并持续验证
3. 审查（20%）：评估产出质量并总结经验
4. 复利（20%）：将结果反馈到系统中，让下一轮循环做得更好

复利式工程的 80% 在规划和审查，20% 在执行。

第 1 步：规划

编写任何代码之前，都要制定全面的计划。好的计划始于研究：

研究阶段

1. 代码库分析：在代码库中搜索类似模式、惯例和先例
2. 提交历史：使用 git log 了解相关功能的构建方式
3. 文档：检查 README、AGENTS.md 和内联文档
4. 外部研究：搜索与问题相关的最佳实践

计划文档结构

创建计划文档（Markdown），包含：

# Feature: [Name]

## Context
- What problem does this solve?
- Who is affected?
- What's the current behavior vs desired behavior?

## Research Findings
- Similar patterns found in codebase: [list with file links]
- Relevant prior implementations: [commit references]
- Best practices discovered: [external references]

## Acceptance Criteria
- [ ] Criterion 1 (testable)
- [ ] Criterion 2 (testable)
- [ ] Criterion 3 (testable)

## Technical Approach
1. Step 1: [specific action]
2. Step 2: [specific action]
3. Step 3: [specific action]

## Code Examples
[Include code snippets that follow existing patterns]

## Testing Strategy
- Unit tests: [what to test]
- Integration tests: [what to test]
- Manual verification: [steps]

## Risks & Mitigations
- Risk 1: [mitigation]
- Risk 2: [mitigation]

详细程度

• 最低：适用于简单功能的快速问题（1-2 小时的工作）
• 标准：涉及技术考量的问题（1-2 天的工作）
• 全面：需要架构决策的重大功能（数天的工作）

第 2 步：执行

系统地执行计划：

执行工作流

1. 创建隔离环境：使用功能分支或 git worktree
2. 拆分任务：根据计划创建 TODO 列表
3. 系统地执行：一次处理一项任务
4. 持续验证：每次改动后运行测试
5. 逐步提交：进行小而集中的提交，并附上清晰的说明

工作原则

• 遵循研究中发现的现有模式
• 每次有意义的改动后运行测试
• 如果出现失败，先弄清原因再继续
• 保持改动聚焦，避免范围蔓延

执行期间的质量检查

# After each change, verify:
npm run typecheck  # or equivalent
npm test           # run affected tests
npm run lint       # check code quality

第 3 步：审查

合并之前，进行全面审查：

审查清单

代码质量

• 遵循现有代码库的模式和惯例
• 没有不必要的复杂性——宁可重复代码，也不要采用错误的抽象
• 命名清晰，并符合项目惯例
• 没有遗留调试代码或 console.logs

安全

• 没有暴露机密或敏感数据
• 在需要的地方进行输入验证
• 安全地处理用户数据

性能

• 没有明显的性能退化
• 数据库查询高效（没有 N+1 问题）
• 适用时采用恰当的缓存

测试

• 测试覆盖验收标准
• 已考虑边界情况
• 测试易于维护，不脆弱

架构

• 改动与系统设计一致
• 没有引入不必要的耦合
• 遵循关注点分离原则

多角度审查

从不同角度审视代码：

• 维护者视角：6 个月后，这项改动是否易于修改？
• 性能视角：是否存在瓶颈？
• 安全视角：是否存在漏洞？
• 简洁性视角：能否做得更简单？

第 4 步：复利

这正是发挥作用的地方——记录经验，让未来的工作更轻松：

复利内容

模式：记录发现或创建的新模式

## Pattern: [Name]
When to use: [context]
Implementation: [example code]
See: [file reference]

决策：记录选择特定方案的原因

## Decision: [Choice Made]
Context: [situation]
Options considered: [alternatives]
Rationale: [why this choice]
Consequences: [trade-offs]

失败：将每个 Bug 转化为经验教训

## Lesson: [What Went Wrong]
Symptom: [what was observed]
Root cause: [actual problem]
Fix: [solution]
Prevention: [how to avoid in future]

将经验教训写入何处

1. AGENTS.md：适用于整个项目的指导原则
2. 子目录中的 AGENTS.md：针对子系统的具体指导原则
3. 内联注释：仅用于代码无法自解释的情况
4. 测试用例：将错误转化为回归测试

在实践中积累经验

完成工作后，问问自己：

• 我学到了什么，值得让其他人知道？
• 我犯了什么错误，可以避免再次发生？
• 我发现或创建了什么模式？
• 做出了什么决策，原因是什么？

将这些内容记录在合适的位置，让未来的 Agent（以及人类）受益。

实用命令

规划功能

Plan implementation for: [describe feature]
- Research the codebase for similar patterns
- Check git history for related changes
- Create a detailed plan with acceptance criteria
- Include code examples that match existing patterns

执行工作

Execute this plan: [plan reference]
- Create feature branch
- Break into TODO list
- Work through systematically
- Run tests after each change
- Create PR when complete

代码审查

Review this change: [PR/diff reference]
- Check for code quality issues
- Look for security concerns
- Evaluate performance implications
- Verify test coverage
- Suggest improvements

积累经验教训

Compound learnings from: [work just completed]
- What patterns were used or created?
- What decisions were made and why?
- What failures occurred and how to prevent them?
- Update AGENTS.md with relevant guidance

核心原则

1. 宁可重复，也不要错误抽象：简单明了的代码胜过复杂的抽象
2. 边做边记录：每条命令都会生成文档，让未来的工作更轻松
3. 质量会不断累积：高质量的代码更易于修改
4. 系统方法胜过个人英雄主义：一致的流程胜过个人的孤军奋战
5. 知识应当形成文档：记录并复用经验教训

成功指标

出现以下情况时，说明你正在有效地积累工程经验：

• 每个功能所需的工作量都少于上一个类似功能
• 错误只发生一次（并且已记录和预防）
• 新团队成员能够快速投入工作（团队知识易于获取）
• 代码审查发现的问题更少（已有模式得到确立并遵循）
• 技术债务随时间减少（经验教训不断积累）

请记住：你不只是在构建功能，也是在构建一个不断改进的开发系统，让它每次使用后都变得更好。