Back to Details

compound-engineering

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese
This skill implements Compound Engineering—a development methodology where each unit of work makes subsequent work easier, not harder. Inspired by Every.to's engineering approach.
本Skill实现了Compound Engineering——一种让每一项工作任务都能让后续工作更轻松（而非更困难）的开发方法论，灵感来源于Every.to的工程实践。

Core Philosophy

核心理念

Each unit of engineering work should make subsequent units of work easier—not harder.
Traditional development accumulates technical debt. Every feature adds complexity. Every change increases maintenance burden. Compound engineering inverts this by creating a learning loop where each bug, failed test, or problem-solving insight gets documented and used by future work.
每一项工程任务都应让后续任务更轻松，而非更困难。
传统开发会积累技术债务，每新增一个功能都会增加复杂度，每一次变更都会提升维护负担。Compound Engineering则通过创建学习循环来反转这一局面：每一个Bug、失败的测试或问题解决思路都会被记录下来，供后续工作使用。

The Compound Engineering Loop

Compound Engineering循环

Plan → Work → Review → Compound → (repeat)
  1. Plan (40%): Research approaches, synthesize information into detailed implementation plans
  2. Work (20%): Execute the plan systematically with continuous validation
  3. Review (20%): Evaluate output quality and identify learnings
  4. Compound (20%): Feed results back into the system to make the next loop better
80% of compound engineering is in planning and review. 20% is in execution.
Plan → Work → Review → Compound → (repeat)
  1. 规划（40%）：研究实现方案，将信息整合为详细的实施计划
  2. 执行（20%）：系统化执行计划，持续验证成果
  3. 评审（20%）：评估输出质量，总结经验教训
  4. 固化（20%）：将结果反馈回系统，让下一次循环更高效
Compound Engineering的80%工作集中在规划和评审阶段，仅20%为执行工作。

Step 1: Plan

步骤1：规划

Before writing any code, create a comprehensive plan. Good plans start with research:
在编写任何代码之前，先创建一份全面的计划。优质的计划始于调研：

Research Phase

调研阶段

  1. Codebase Analysis: Search for similar patterns, conventions, and prior art in the codebase
  2. Commit History: Use 
    git log
    to understand how related features were built
  3. Documentation: Check README, AGENTS.md, and inline documentation
  4. External Research: Search for best practices relevant to the problem
  1. 代码库分析：在代码库中查找类似的模式、规范和已有实现
  2. 提交历史：使用
    git log
    了解相关功能的构建过程
  3. 文档查阅：查看README、AGENTS.md和内联文档
  4. 外部调研：搜索与当前问题相关的最佳实践

Plan Document Structure

计划文档结构

Create a plan document (markdown) with:
markdown
undefined
创建一份Markdown格式的计划文档，包含以下内容：
markdown
undefined

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)
  • 标准1（可测试）
  • 标准2（可测试）
  • 标准3（可测试）

Technical Approach

技术方案

  1. Step 1: [specific action]
  2. Step 2: [specific action]
  3. Step 3: [specific action]
  1. 步骤1：[具体操作]
  2. 步骤2：[具体操作]
  3. 步骤3：[具体操作]

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]
undefined
  • 风险1：[应对方案]
  • 风险2：[应对方案]
undefined

Detail Levels

详细程度

  • Minimal: Quick issues for simple features (1-2 hours work)
  • Standard: Issues with technical considerations (1-2 days work)
  • Comprehensive: Major features requiring architecture decisions (multi-day work)
  • 极简版：适用于简单功能的快速任务（1-2小时工作量）
  • 标准版：适用于涉及技术考量的任务（1-2天工作量）
  • 完整版：适用于需要架构决策的大型功能（多天工作量）

Step 2: Work

步骤2：执行

Execute the plan systematically:
系统化执行计划：

Execution Workflow

执行工作流

  1. Create isolated environment: Use feature branch or git worktree
  2. Break down into tasks: Create TODO list from plan
  3. Execute systematically: One task at a time
  4. Validate continuously: Run tests after each change
  5. Commit incrementally: Small, focused commits with clear messages
  1. 创建隔离环境：使用功能分支或git worktree
  2. 拆分任务：根据计划创建待办事项列表
  3. 系统化执行：逐个完成任务
  4. 持续验证：每次变更后运行测试
  5. 增量提交：提交小型、聚焦的变更，并附上清晰的提交信息

Working Principles

执行原则

  • Follow existing patterns discovered in research
  • Run tests after every meaningful change
  • If something fails, understand why before proceeding
  • Keep changes focused—don't scope creep
  • 遵循调研中发现的现有模式
  • 每次有意义的变更后都运行测试
  • 若出现失败，先理解原因再继续
  • 保持变更聚焦——不要扩大范围

Quality Checks During Work

执行中的质量检查

bash
undefined
bash
undefined

After each change, verify:

每次变更后，验证以下内容：

npm run typecheck # or equivalent npm test # run affected tests npm run lint # check code quality
undefined
npm run typecheck # 或等效命令 npm test # 运行受影响的测试 npm run lint # 检查代码质量
undefined

Step 3: Review

步骤3：评审

Before merging, perform comprehensive review:
合并之前，执行全面的评审：

Review Checklist

评审检查清单

Code Quality
  • Follows existing codebase patterns and conventions
  • No unnecessary complexity—prefer duplication over wrong abstraction
  • Clear naming that matches project conventions
  • No debug code or console.logs left behind
Security
  • No secrets or sensitive data exposed
  • Input validation where needed
  • Safe handling of user data
Performance
  • No obvious performance regressions
  • Database queries are efficient (no N+1)
  • Appropriate caching if applicable
Testing
  • Tests cover acceptance criteria
  • Edge cases considered
  • Tests are maintainable, not brittle
Architecture
  • Change is consistent with system design
  • No unnecessary coupling introduced
  • Follows separation of concerns
代码质量
  • 符合现有代码库的模式和规范
  • 无不必要的复杂度——宁要重复，不要错误的抽象
  • 命名清晰，符合项目规范
  • 无遗留的调试代码或console.log
安全性
  • 未暴露密钥或敏感数据
  • 必要处添加了输入验证
  • 用户数据处理安全
性能
  • 无明显的性能退化
  • 数据库查询高效（无N+1问题）
  • 适用时使用了恰当的缓存策略
测试
  • 测试覆盖了验收标准
  • 考虑了边缘情况
  • 测试可维护，不脆弱
架构
  • 变更与系统设计一致
  • 未引入不必要的耦合
  • 遵循关注点分离原则

Multi-Perspective Review

多视角评审

Consider the code from different angles:
  • Maintainer perspective: Will this be easy to modify in 6 months?
  • Performance perspective: Any bottlenecks?
  • Security perspective: Any vulnerabilities?
  • Simplicity perspective: Can this be simpler?
从不同角度审视代码：
  • 维护者视角：6个月后修改这段代码会容易吗？
  • 性能视角：是否存在瓶颈？
  • 安全视角：是否存在漏洞？
  • 简洁性视角：这段代码能更简单吗？

Step 4: Compound

步骤4：固化

This is where the magic happens—capture learnings to make future work easier:
这是核心价值所在——将经验教训记录下来，让未来的工作更轻松：

What to Compound

固化内容

Patterns: Document new patterns discovered or created
markdown
undefined
模式：记录发现或创建的新模式
markdown
undefined

Pattern: [Name]

模式：[名称]

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

**Decisions**: Record why certain approaches were chosen
```markdown
适用场景：[上下文] 实现方式：[示例代码] 参考：[文件引用]

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

Decision: [Choice Made]

决策：[所选方案]

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

**Failures**: Turn every bug into a lesson
```markdown
背景：[场景] 考虑的选项：[替代方案] 理由：[选择该方案的原因] 影响：[权衡结果]

**失败案例**：将每一个Bug转化为经验教训
```markdown

Lesson: [What Went Wrong]

经验教训：[问题所在]

Symptom: [what was observed] Root cause: [actual problem] Fix: [solution] Prevention: [how to avoid in future]
undefined
症状：[观察到的现象] 根本原因：[实际问题] 修复方案：[解决方法] 预防措施：[未来如何避免]
undefined

Where to Codify Learnings

固化位置

  1. AGENTS.md: Project-wide guidance that applies everywhere
  2. Subdirectory AGENTS.md: Specific guidance for subsystems
  3. Inline comments: Only when the code isn't self-explanatory
  4. Test cases: Turn bugs into regression tests
  1. AGENTS.md：适用于全项目通用的指导原则
  2. 子目录AGENTS.md：适用于子系统的特定指导
  3. 内联注释：仅当代码无法自解释时使用
  4. 测试用例：将Bug转化为回归测试

Compounding in Practice

固化实践

After completing work, ask:
  • What did I learn that others should know?
  • What mistake did I make that can be prevented?
  • What pattern did I discover or create?
  • What decision was made and why?
Document these in the appropriate location so future agents (and humans) benefit.
完成工作后，思考以下问题：
  • 我学到了什么值得他人知晓的内容？
  • 我犯了什么可以预防的错误？
  • 我发现或创建了什么模式？
  • 做出了什么决策，原因是什么？
将这些内容记录在合适的位置，让未来的Agent（以及人类开发者）都能从中受益。

Practical Commands

实用命令

Planning a Feature

规划功能

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
规划实现方案：[描述功能]
- 调研代码库中的类似模式
- 查看git历史中的相关变更
- 创建包含验收标准的详细计划
- 加入符合现有模式的代码示例

Executing Work

执行工作

Execute this plan: [plan reference]
- Create feature branch
- Break into TODO list
- Work through systematically
- Run tests after each change
- Create PR when complete
执行该计划：[计划引用]
- 创建功能分支
- 拆分为待办事项列表
- 系统化完成任务
- 每次变更后运行测试
- 完成后创建PR

Reviewing Code

评审代码

Review this change: [PR/diff reference]
- Check for code quality issues
- Look for security concerns
- Evaluate performance implications
- Verify test coverage
- Suggest improvements
评审此变更：[PR/差异引用]
- 检查代码质量问题
- 排查安全隐患
- 评估性能影响
- 验证测试覆盖率
- 提出改进建议

Compounding Learnings

固化经验

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
固化以下工作的经验：[刚完成的工作]
- 使用或创建了什么模式？
- 做出了什么决策，原因是什么？
- 发生了什么失败，如何预防？
- 更新AGENTS.md中的相关指导

Key Principles

核心原则

  1. Prefer duplication over wrong abstraction: Simple, clear code beats complex abstractions
  2. Document as you go: Every command generates documentation that makes future work easier
  3. Quality compounds: High-quality code is easier to modify
  4. Systematic beats heroic: Consistent processes beat individual heroics
  5. Knowledge should be codified: Learnings should be captured and reused
  1. 宁要重复，不要错误的抽象：简洁清晰的代码优于复杂的抽象
  2. 边做边记录：每一条命令都会生成文档，让未来工作更轻松
  3. 质量会积累：高质量代码更易于修改
  4. 系统化优于英雄主义：一致的流程胜过个人英雄式的操作
  5. 知识应被固化：经验教训应被记录并复用

Success Metrics

成功指标

You're doing compound engineering well when:
  • Each feature takes less effort than the last similar feature
  • Bugs become one-time events (documented and prevented)
  • New team members can be productive quickly (institutional knowledge is accessible)
  • Code reviews surface fewer issues (patterns are established and followed)
  • Technical debt decreases over time (learnings compound)
Remember: You're not just building features—you're building a development system that gets better with each use.
当你满足以下条件时，说明Compound Engineering实践得很好：
  • 每一个同类功能的开发成本都比上一个更低
  • Bug成为一次性事件（已被记录并预防）
  • 新团队成员能快速上手（机构知识易于获取）
  • 代码评审中发现的问题越来越少（模式已建立并被遵循）
  • 技术债务随时间减少（经验不断积累）
请记住：你不只是在构建功能——你正在构建一个越用越好的开发系统。