Compound Engineering: Biến Mỗi Đơn Vị Công Việc Thành Nền Tảng Cho Công Việc Tiếp Theo

Triết lý

Triết lý cốt lõi của compound engineering là: mỗi đơn vị công việc kỹ thuật phải giúp các đơn vị công việc sau trở nên dễ dàng hơn — chứ không phải khó hơn.

Hầu hết các codebase theo thời gian đều trở nên khó làm việc hơn, bởi vì mỗi tính năng mới lại đưa thêm độ phức tạp vào hệ thống. Sau 10 năm, các nhóm phát triển thường dành nhiều thời gian để vật lộn với hệ thống cũ hơn là xây dựng thêm chức năng mới, bởi vì mỗi tính năng mới phải "đàm phán" với các tính năng cũ.

Theo thời gian, codebase trở nên:

• Khó hiểu hơn
• Khó sửa đổi hơn
• Khó tin tưởng hơn

Compound engineering đảo ngược hoàn toàn điều đó. Thay vì mỗi tính năng làm tăng độ phức tạp và sự mong manh của hệ thống, mỗi tính năng dạy cho hệ thống một năng lực mới.

Ví dụ:

• Các bug fix có thể loại bỏ cả một lớp lỗi trong tương lai
• Các pattern khi được chuẩn hóa trở thành công cụ cho công việc sau này

Theo thời gian, codebase trở nên:

• Dễ hiểu hơn
• Dễ sửa đổi hơn
• Dễ tin tưởng hơn

Vòng lặp chính

Every vận hành năm sản phẩm: Cora, Monologue, Sparkle, Spiral, Website Every.to — mỗi sản phẩm chủ yếu chỉ có một kỹ sư phụ trách.

Điều khiến việc này khả thi là một vòng lặp bốn bước, nền tảng của compound engineering:

Plan → Work → Review → Compound → Repeat

Ba bước đầu tiên — Plan, Work, Review — quen thuộc với mọi developer. Điểm khác biệt nằm ở bước thứ tư: Compound. Đây là nơi lợi ích tích lũy xuất hiện. Nếu bạn bỏ qua bước này, bạn chỉ đang làm kỹ thuật phần mềm truyền thống có hỗ trợ AI.

Vòng lặp này hoạt động giống nhau cho mọi quy mô công việc:

• Sửa bug trong 5 phút
• Xây tính năng trong nhiều ngày

Theo nguyên tắc:

Plan + Review = 80% thời gian Work + Compound = 20%

Nói cách khác: phần lớn suy nghĩ xảy ra trước và sau khi viết code.

1. Plan (Lập kế hoạch)

Planning biến một ý tưởng thành bản thiết kế (blueprint). Kế hoạch tốt → kết quả tốt.

Các bước cần thực hiện:

Hiểu yêu cầu

• Cần xây dựng gì?
• Tại sao cần xây dựng?
• Có những ràng buộc nào?

Nghiên cứu codebase

• Chức năng tương tự hoạt động như thế nào?
• Có pattern nào đang tồn tại?

Nghiên cứu bên ngoài

• Documentation của framework nói gì?
• Best practice trong ngành là gì?

Thiết kế giải pháp

• Cách tiếp cận là gì?
• Những file nào cần thay đổi?

Xác thực kế hoạch

• Kế hoạch có hợp lý không?
• Có thiếu phần nào không?

2. Work (Thực thi)

Execution phải tuân theo kế hoạch. Agent thực hiện, developer giám sát.

Các nhiệm vụ trong bước này:

Thiết lập môi trường cô lập

• Sử dụng: Git worktrees (bản sao repo tách biệt) hoặc branch

Thực thi kế hoạch

• Agent triển khai từng bước

Chạy kiểm tra — sau mỗi thay đổi:

• Chạy test
• Chạy lint
• Kiểm tra type

Theo dõi tiến độ

• Việc nào đã hoàn thành
• Việc nào còn lại

Xử lý vấn đề

• Nếu có lỗi → điều chỉnh kế hoạch

Nếu kế hoạch đáng tin cậy, bạn không cần xem từng dòng code.

3. Review (Đánh giá)

Bước này giúp phát hiện vấn đề trước khi code được deploy. Quan trọng hơn, nó ghi lại bài học cho vòng lặp tiếp theo — nền tảng của compound engineering.

Các hoạt động trong bước review:

Nhiều agent review code

• Các reviewer chuyên biệt kiểm tra code song song

Ưu tiên vấn đề — phân loại:

• P1 — bắt buộc sửa
• P2 — nên sửa
• P3 — sửa nếu tiện

Giải quyết vấn đề

• Agent sửa lỗi theo feedback

Xác thực sửa lỗi

• Đảm bảo sửa đúng và đầy đủ

Ghi lại pattern

• Tài liệu hóa lỗi để tránh lặp lại

4. Compound (Bước quan trọng nhất)

Phát triển truyền thống thường dừng ở bước Review. Nhưng Compound mới là nơi tạo ra lợi ích lâu dài.

Ba bước đầu tạo ra: một tính năng Bước thứ tư tạo ra: một hệ thống có thể tạo ra tính năng tốt hơn mỗi lần

Các việc cần làm:

Ghi lại giải pháp — tự hỏi:

• Điều gì đã hoạt động tốt?
• Điều gì không hiệu quả?
• Insight nào có thể tái sử dụng?

Làm cho thông tin dễ tìm

• Thêm YAML frontmatter: metadata, tags, categories

Cập nhật hệ thống

• Thêm pattern mới vào CLAUDE.md
• Tạo agent mới nếu cần

Xác minh bài học — tự hỏi:

• Lần sau hệ thống có tự động bắt được lỗi này không?

Plugin

Workflow compound engineering được phát hành dưới dạng plugin. Cài đặt plugin → toàn bộ hệ thống sẵn sàng sử dụng.

Bên trong plugin có gì

• 26 agent chuyên biệt
• 23 workflow command
• 13 skill — cung cấp kiến thức chuyên môn như: kiến trúc agent-native, style guide

Cài đặt

Claude Code

claude /plugin marketplace add https://github.com/EveryInc/every-marketplace
claude /plugin install compound-engineering

OpenCode (experimental)

bunx @every-env/compound-plugin install compound-engineering --to opencode

Codex (experimental)

bunx @every-env/compound-plugin install compound-engineering --to codex

Cấu trúc thư mục hệ thống

your-project/
├── CLAUDE.md
├── docs/
│   ├── brainstorms/
│   ├── solutions/
│   └── plans/
└── todos/

CLAUDE.md

File quan trọng nhất. Agent đọc file này ở đầu mỗi session. Nên đặt trong file:

• preferences
• coding patterns
• project context

Nếu có lỗi xảy ra → ghi chú vào đây để agent học.

docs/solutions/

Thư mục này xây dựng kiến thức tổ chức (institutional knowledge). Mỗi vấn đề được giải quyết sẽ trở thành documentation có thể tìm kiếm. Session sau có thể tự động tìm lại.

todos/

Thư mục này theo dõi công việc: priority, trạng thái.

Ví dụ:

001-ready-p1-fix-auth.md
002-pending-p2-add-tests.md

Cấu trúc Plugin

agents/
├── review/     # 14 chuyên gia review code
├── research/   # Agent nghiên cứu codebase và tài liệu
├── design/     # Agent giao diện người dùng và đồng bộ Figma
├── workflow/   # Agent tự động hóa workflow
└── docs/       # Agent tạo tài liệu
commands/
├── workflows/  # Các lệnh của vòng lặp chính
└── *.md        # Các lệnh tiện ích
skills/         # Kiến thức chuyên môn (14 skill)

Các lệnh cốt lõi (Core Commands)

/workflows:brainstorm

Khi bạn chưa chắc nên xây dựng gì, hãy bắt đầu ở đây.

/workflows:brainstorm Add user notifications

Cách hoạt động:

• Chạy nghiên cứu nhẹ trên repo
• Hỏi từng câu hỏi một để làm rõ: mục tiêu, người dùng, ràng buộc, edge cases
• AI đề xuất các cách tiếp cận
• Các quyết định được lưu vào docs/brainstorms/ để dùng cho bước tiếp theo: /workflows:plan

/workflows:plan

Mô tả điều bạn muốn → AI trả lại kế hoạch xây dựng chi tiết.

/workflows:plan Add email notifications when users receive new comments

Lệnh này khởi chạy 3 agent nghiên cứu song song:

• repo-research-analyst — phân tích pattern trong codebase
• framework-docs-researcher — đọc documentation của framework
• best-practices-researcher — tìm best practice của ngành

Sau đó agent spec-flow-analyzer:

• phân tích user flow
• phân tích edge cases

Kết quả cuối cùng là một plan có cấu trúc, gồm:

• danh sách file bị ảnh hưởng
• các bước implementation

Chế độ Ultrathink

Có thể bật chế độ ultrathink (lập luận mở rộng). Chế độ này sẽ tự động chạy /deepen-plan sau khi plan được tạo — khởi chạy hơn 40 agent nghiên cứu song song để đào sâu kế hoạch.

/workflows:work

Đây là nơi agent thực sự viết code.

Quy trình gồm 4 giai đoạn:

1. Quick start — tạo git worktree, tạo branch riêng
2. Execute — Agent triển khai từng task với progress tracking
3. Quality check — Khởi chạy hơn 5 agent reviewer: Rails, TypeScript, Security, Performance
4. Ship it — chạy lint, tạo Pull Request

Mỗi giai đoạn đều có điểm bắt đầu và kết thúc rõ ràng.

/workflows:review

Review Pull Request bằng hơn một chục agent chuyên biệt.

/workflows:review PR#123

Lệnh này khởi chạy 14 agent chuyên môn song song, bao gồm:

• security-sentinel
• performance-oracle
• data-integrity-guardian
• architecture-strategist
• pattern-recognition-specialist
• code-simplicity-reviewer
• Reviewer theo framework: Rails, TypeScript, Python

Tất cả kết quả được tổng hợp thành danh sách ưu tiên duy nhất.

Review Agents

Lệnh /review sinh ra 14 agent review chuyên biệt. Mỗi agent kiểm tra một khía cạnh cụ thể của code.

Security

• security-sentinel — Quét: Top 10 lỗ hổng theo OWASP, SQL injection, lỗi xác thực, bypass authorization

Performance

• performance-oracle — Phát hiện: N+1 query, index bị thiếu, cơ hội caching, bottleneck thuật toán

Architecture

• architecture-strategist — Đánh giá: thiết kế hệ thống, ranh giới component, hướng dependency
• pattern-recognition-specialist — Phát hiện: design pattern, anti-pattern, code smell

Data

• data-integrity-guardian — Xác thực: migration, transaction boundary, referential integrity
• data-migration-expert — Kiểm tra: mapping ID, rollback safety, validation dữ liệu production

Quality

• code-simplicity-reviewer — Áp dụng nguyên tắc YAGNI (You Aren't Gonna Need It): phát hiện complexity không cần thiết, kiểm tra readability
• kieran-rails-reviewer — Kiểm tra: Rails conventions, Turbo Streams, phân tách model/controller
• kieran-python-reviewer — Kiểm tra: chuẩn PEP 8, type hints, idiom Python
• kieran-typescript-reviewer — Kiểm tra: type safety, ES pattern hiện đại, clean architecture
• dhh-rails-reviewer — Theo triết lý 37signals: đơn giản hơn, abstraction stack Omakase

Deployment

• deployment-verification-agent — Tạo: checklist trước deploy, checklist sau deploy, rollback plan

Frontend

• julik-frontend-races-reviewer — Phát hiện: race condition trong JavaScript, race condition trong Stimulus controller

Agent-native

• agent-native-reviewer — Kiểm tra xem tính năng có thể truy cập bởi agent không, hay chỉ dành cho con người

Định dạng Output

Kết quả review được nhóm theo mức ưu tiên:

P1 - CRITICAL (bắt buộc sửa):
[ ] SQL injection vulnerability in search query (security-sentinel)
[ ] Missing transaction around user creation (data-integrity-guardian)

P2 - IMPORTANT (nên sửa):
[ ] N+1 query in comments loading (performance-oracle)
[ ] Controller doing business logic (kieran-rails-reviewer)

P3 - MINOR (tùy chọn):
[ ] Unused variable (code-simplicity-reviewer)
[ ] Could use guard clause (pattern-recognition-specialist)

Tự động sửa lỗi

/resolve_pr_parallel

Lệnh này xử lý toàn bộ findings tự động.

Quy trình:

1. Sửa tất cả P1 trước
2. Sau đó sửa P2

Mỗi fix chạy trong môi trường cô lập để tránh xung đột. Sau khi hoàn thành, bạn vẫn review thủ công các fix được tạo.

/triage

Lệnh này giúp con người quyết định từng issue.

Mỗi finding được hiển thị lần lượt. Bạn có thể:

• approve → thêm vào todo list
• skip → bỏ qua
• customize → chỉnh priority

Các item được approve sẽ có trạng thái ready, sau đó có thể xử lý bằng /resolve_todo_parallel.

/workflows:compound

Lệnh này dùng để ghi lại một vấn đề đã được giải quyết.

/workflows:compound

Nó khởi chạy 6 sub-agent song song:

Kết quả là một file markdown có thể tìm kiếm với YAML metadata.

/lfg

Lệnh này là pipeline đầy đủ. Bạn chỉ cần mô tả tính năng. Agent làm tất cả.

/lfg Add dark mode toggle to settings page

Pipeline chạy:

plan → deepen-plan → work → review → resolve → browser tests → feature video → compound

• Dừng để bạn approve plan
• Sau đó chạy tự động

Lệnh này có thể spawn hơn 50 agent. Kết quả cuối cùng: một Pull Request hoàn chỉnh.

Phần tiếp theo bao gồm: 8 niềm tin sai lầm trong lập trình truyền thống, quy tắc 50/50, agent-native environment, parallel agent workflow, 5 cấp độ trưởng thành AI developer, và nhiều hơn nữa.