"Compound Engineering"를 읽고

AR-DA-01calendar_today2026-02-11 06:48

1. 글이 제기하는 문제의식

  • 대부분 코드베이스는 기능을 추가하면서 복잡도와 취약성이 누적된다.
    • 이는 시간이 갈 수록 "이해, 수정, 신뢰"가 어려워지는 것을 초래함.
  • Compound engineering이란 그것을 뒤집어, 기능/버그수정이 끝날 때마다 시스템을 더 똑똑해지게 만들자는 접근

1.1. 저자가 제시하는 Main Loop

  • Plan -> Work -> Review -> Compound -> Repeat 임
    • 핵심은 Compound 단계임.
      • 이게 없으면 AI 도움을 받는 일반 개발과 다르지 않다.
    • Plan, Work, Review는 솔직히 익숙함

2. 그래서 Compound 단계는 뭐하는 단계?

아래와 같은 축적물을 만들어 내는 것.

  1. 버그를 한 번의 수정으로 끝내지 않고, 재발을 원천 차단하는 테스트/가드레일로 승격
    • 크래시/로그 기반 재현 -> 해결 -> 테스트까지
  2. 결정(트레이드오프/이유)을 문서화하여 다음에 같은 토론을 반복하지 않기
  3. 리뷰를 역할별 에이전트로 분업(스타일/프레임워크/성능 등) 해서 사람의 수동 리뷰 부담을 시스템으로 옮기기
  4. UI 변경 같은 것도 자동 스냅샷/비교로 문서화해서 회귀를 빨리 잡기
  5. 내 취향/기준을 시스템으로 추출하여 다음부턴 에이전트가 처음부터 그 기준을 반영하게 만들기
    • 세션 시작 규칙 파일
    • 프롬프트
    • 스킬
    • 체크리스트

2.1. 운영 디테일

  • 해당 루프는 5분 짜리 버그 수정이든 며칠짜리 기능이든 동일하게 적용해야함.
    • 그저 규모만 달라질 뿐
  • Work 단계에서 git worktree 같은 격리된 작업 공간을 강조하여 병렬 작업/혼선을 줄이는 방법
  • 몇 달 적용했을 때 배포 속도, 리뷰 속도, 사전 버그 포착이 개선되었다는 정량적 결과를 한번 내보기

3. 나에게 맞는 방법

  • 글의 핵심을 이러하다.
    • 4단계 루프 : Plan -> Work -> Review -> Compound 를 반복.
    • 시간 배분은 Plan, Review가 80%이고 나머지가 20%
      • 코드 작성보다 설계 및 검토가 중요
  • 저자는 Claude를 사용하는 것으로 보인다.
    • 하지만 나는 ChatGPT + Codex를 사용한다.
    • 크게 달라질건 없고, Claude/플러그인 같은 도구를 Codex에 맞게 치환
      • Git Worktree는 어차피 동일하게 사용.

3.1. 나에게 맞는 실전 루프

3.1.1. Plan

  • 구현 요청 전, 아래 산출물을 먼저 받아서 검토해야함
    • 요구사항/제약 정리
      • 무엇을 만들것인지, 왜 이것이 필요한지, 제약은 어떤게 있는지
    • 프로젝트 내 유사 패턴 조사
      • 프로젝트 내에 유사 패턴이 있는지, 참고할 수 있는 곳이 있는지 제공
    • 외부에 있는 Best Practice나 Framework 기준이 있는지
      • Context7 MCP를 잘 활용해 볼까?
    • 변경 파일 목록 + 단계별 체크리스트
    • 계획 자체 검증(내 계획에 빠진게 없는지)
  • 위 과정은 ChatGPT를 이용해 교차 검증하는게 좋을 듯함.
  • 계획을 먼저, 구현은 해당 계획을 승인한 후 고정 프롬프트로 만들면 루프가 안정적임

3.1.2. Work

  • 격리가 중요하다.
    • worktree/branch 활용
    • 하지만 병렬작업이나 안정성을 위해 branch대신 물리적으로 나눠주는 worktree를 선호
  • AR-DA-01 "Compound Engineering"를 읽고#3.1.1. Plan에서 세운 Plan으로 단계적 구현을 실시함
  • 각 변경마다 테스트/린트/타입체크 검증을 수행해야함
  • 진행사항을 추적하고 문제 발생 시 계획을 조정해야함.

3.1.3. Review

  • 전문 리뷰어 에이전트가 병렬로 검토, 결과를 P1/P2/P3로 우선순위화 하라고 한다.
  • 내 환경에 맞춘다면
    • Codex 여러 모델에서 검증 실시
    • 리뷰 관점을 "보안/성능/데이터 무결성/구조/단순성/회귀"처럼 역할 기반 체크리스트로 고정
    • 이슈는 P1/P2/P3로 분류후 어디까지 지금 고칠지 결정을 쉽게 하기

3.1.4. Compound

  • 가장 중요한 부분, 다음 작업을 더욱 쉽게 만드는게 중요한 지점
  • 저자가 말하는 액션을 4가지로 요약
    1. 해결책에서 재사용 인사이트를 추출
    2. 찾기 쉽게 만들기(YAML frontmatter로 태깅/분류)
    3. 시스템 업데이트(세션 시작 파일/에이전트/패턴 업데이트)
    4. 다음엔 자동으로 실수가 잡히는지 자문해야함
  • 내 환경에 맞춘다면
    • docs/solutions같은 폴더를 두고 발생한 문제/해결/재발방지문서를 남긴다.
    • AGENTS.MD에 규칙/패턴으로 다음부터 이렇게 하라라는 내용을 추가한다.
    • 다음에 Codex가 동일한 실수를 하는지 체크

3.2. 프로젝트 구조를 해당 글 방식으로 맞춘다면

  • 저자의 글에는 "어디에 무엇을 둘지"가 꽤나 구체적으로 드러나 있음
  • AGENTS.MD
    • Codex 세션 시작 규칙/패턴/선호/금지/품질 기준의 단일 진실원
  • docs/
    • plans/ : Plan 산출물 저장
    • solutions/ : Compound 산출물 저장(재사용 지식)
    • brainstorms/ : 요구가 애매할 때 탐색 기록
  • todos/
    • 리뷰에 나온 P1/P2/P3 이슈를 "상태(status)"와 함께 관리

3.3. Compound 문서의 최소 템플릿

markdown 
---
title: "<문제 한 줄 요약>"
tags: ["compound", "<도메인>", "<키워드>"]
severity: "P1|P2|P3"
related: ["<관련 파일/PR/이슈 링크 또는 식별자>"]
---

## 문제
- 증상:
- 재현 조건:
- 근본 원인(추정/확정):

## 해결
- 적용한 접근:
- 변경 범위(파일/모듈):
- 트레이드오프:

## 검증
- 확인한 테스트:
- 추가로 봐야 할 회귀 포인트:

## 재발 방지(시스템 업데이트)
- AGENTS.MD에 추가할 규칙/패턴:
- 다음부터 자동으로 잡히게 할 장치(테스트/린트/체크리스트):
  • 해당 문서를 docs/solutions/에 쌓아 다음 Codex에게 "관련 Solution을 찾아 피하라"가 가느해진다.