compound-engineering

このスキルは、各作業単位によって後続の作業が難しくなるのではなく、容易になる開発手法「コンパウンドエンジニアリング」を実践します。Every.to のエンジニアリング手法に着想を得ています。

中核となる理念

エンジニアリングの各作業単位によって、後続の作業単位が難しくなるのではなく、容易になるべきです。

従来の開発では、技術的負債が蓄積します。機能を追加するたびに複雑さが増し、変更するたびにメンテナンスの負担が大きくなります。コンパウンドエンジニアリングでは、バグ、テストの失敗、問題解決から得た知見を記録し、後続の作業に活用する学習ループを作ることで、この流れを逆転させます。

コンパウンドエンジニアリングのループ

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. 体系的に実行する：一度に1つのタスクに取り組みます
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]

失敗：あらゆるバグを教訓に変えます

## 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. テストケース：バグを回帰テストにします

実践で積み重ねる

作業を終えたら、次のことを考えてください。

• 他の人にも知ってもらうべき学びは何ですか？
• 防ぐことのできるミスはありましたか？
• 発見した、または作成したパターンはありますか？
• どのような判断をし、その理由は何ですか？

今後のエージェント（と人間）の役に立つよう、適切な場所に記録してください。

実用的なコマンド

機能の計画

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. 知識は記録する：学びを記録し、再利用できるようにします

成功の指標

次のような状態であれば、複利的なエンジニアリングをうまく実践できています。

• 機能の実装にかかる労力が、同様の機能を実装するたびに減っている
• バグが一度限りのものになっている（記録され、再発を防げている）
• 新しいチームメンバーがすぐに戦力になれる（組織の知識にアクセスできる）
• パターンが確立され、守られることで、コードレビューで見つかる問題が減っている
• 学びが積み重なり、技術的負債が時間とともに減っている

忘れないでください。構築しているのは機能だけではありません。使うたびに改善される開発システムも構築しているのです。