insong
← 위키 2026년 4월 20일

메인세션 = 티켓 단위 워크플로우

한 티켓의 설계–구현–리뷰 반영을 하나의 메인세션이 담당하되, 문서화·평가 기준 추출·코드 리뷰는 fork/sub-agent로 분리해 context를 보존하는 패턴

Claude AI workflow context code-review

핵심 원칙

메인세션 하나는 티켓 하나를 처음부터 끝까지 들고 간다 — 요구사항 구체화 → 설계 → 구현 → 리뷰 반영 완료.

메인세션의 토큰 공간은 이번 작업의 원재료(요구사항·설계·구현)에만 쓴다. 문서화·평가 기준 추출·코드 리뷰는 전부 메인세션 밖에서 수행한다.

근거: context를 적게 쓸수록 결과물이 좋다. Context가 차면 AI가 서둘러 끝내려 하고, 대강 봉합하는 경향이 나타난다.

단계별 구조

1단계 — 요구사항 + 설계 (메인세션)

요구사항을 구체화하고 아키텍처를 설계한다. 설계가 끝난 시점의 메인세션에는 “왜 이 선택을 했는가”의 생생한 맥락이 있다.

2단계 — 설계 의도 문서화 (Fork)

메인세션을 fork한다. Fork한 쪽이 설계 의도 문서 작성 + ADR 업데이트를 수행하고 폐기한다.

  • 같은 메인세션에게 시키지 않는 이유: 문서 작성이 구현용 context를 갉아먹는다
  • 문서만 넘겨 새 세션을 파지 않는 이유: 문서에 담기지 않는 암묵적 맥락(버려진 대안, 네이밍 이유 등)이 설계자 머릿속에 남는다. Fork가 그 순간을 그대로 담는 가장 가까운 방법이다

Fork 용도 일반화: 설계 의도 기록만 fork 용도가 아니다. UI 구조 결정처럼 합의가 오래 걸리는 논의도 fork에서 수행하고 결론만 메인세션에 들여온다. 원칙: 길어질 가능성이 있는 논의는 fork에서 끝내고 결과만 가져온다.

3단계 — 평가 기준 추출 (Sub-agent)

별도 sub-agent가 프로젝트의 coding convention과 ADR을 훑어 이번 작업에 필요한 부분만 code-quality-guide.md로 정리한다. 사람이 검토한다.

  • 메인세션에 전체 convention/ADR을 넣지 않는 이유: 프로젝트가 오래될수록 커진다. 이번 티켓과 무관한 규칙까지 들어가면 context 낭비

4단계 — 구현 (메인세션 + guide)

메인세션이 code-quality-guide.md를 참고해 구현한다.

5단계 — 리뷰 (별도 리뷰 agent + guide)

별도 agent가 새 세션에서 같은 code-quality-guide.md를 판정 기준으로 리뷰한다. 세션이 분리되어 있어 남이 읽는 것과 비슷한 방식으로 코드를 본다.

6단계 — 리뷰 반영 (메인세션)

리뷰 피드백을 메인세션에서 반영한다. 구현한 세션이 수정까지 들고 있어야 “왜 그렇게 짰는지”를 잃지 않는다. 메인세션은 리뷰 반영 완료까지 유지된다.

code-quality-guide.md의 이중 사용

같은 가이드가 라이프사이클의 두 지점에서 재사용된다.

사용 지점역할
구현 단계메인세션이 따르는 코딩 기준
리뷰 단계리뷰 agent가 쓰는 판정 기준

같은 기준으로 만들고 같은 기준으로 검증 → 코드는 만들어지는 순간부터 평가 기준을 알고 있다.

AI 리뷰가 초기에 부족했던 이유 — 맥락 격차

사람 동료가 리뷰할 때 쥐고 있는 세 가지 암묵 맥락을 AI는 기본적으로 갖고 있지 않다.

사람 동료가 쥔 맥락외재화 방법
조직이 공유하는 “예쁜 코드”의 기준 (문서화 안 된 스타일 감각)code-convention.md로 명시화
이 작업 설계자의 구체적 의도 (왜 이렇게, 왜 다른 방식은 버렸는가)adr.md로 누적 기록
모르겠으면 설계자에게 물어보는 경로ADR이 누적되어 있으면 대부분 해소

→ AI에게 그냥 “리뷰해줘”라고 하면 위 맥락이 없어 피상적. 위의 두 문서를 함께 넘기면 사람 리뷰와 구별 어려움.

리뷰 기준 두 문서

문서성격
code-convention.md언제나 참고하는 코딩 지침. 언어별로 여러 개 가능
adr.md기술적 결정 기록. 결정 결과뿐 아니라 무엇을 고민했고 왜 이걸 골랐는지가 누적됨. 시간이 지날수록 커진다

이 둘이 잘 쌓이면 AI 리뷰와 사람 리뷰를 구별하기 어렵다.

사람 역할 변화

  • 사람 리뷰는 작업 전에 끝난다 — 설계 의도 문서 검토 + 평가 기준 검토 두 번
  • 작업 후 코드 리뷰는 agent가 수행
  • 보안·결제처럼 중요한 영역은 여전히 사람이 리뷰할 수 있지만, 해당 영역의 판단 기준을 ADR에 잘 써두면 AI가 대부분 잡는다

ADR을 놓치지 않고 쌓는 규율이 사람 리뷰 없이 굴러가는 시스템의 전제조건.

전체 흐름

요구사항 + 설계                 [메인세션]
    │
    ├─ fork → 설계의도 + ADR 갱신 → 폐기       [fork]
    │
    ├─ sub-agent → code-quality-guide.md       [별도 세션]
    │         ↓
    │      사람 검토
    │
구현                              [메인세션 + guide]
    │
    ├─ 리뷰 agent → 리뷰 리포트                [별도 세션 + guide]
    │
리뷰 반영                         [메인세션]
    │
    완료

세션 책임 분리

세션담당
메인세션요구사항·설계·구현·리뷰 반영
Fork설계 의도 문서 + ADR (1회성, 폐기)
Sub-agent평가 기준(code-quality-guide.md) 추출
리뷰 agentcode-quality-guide.md 기반 판정

Takeaway

AI 워크플로우 설계의 핵심 질문은 “어떤 context를 어느 세션에 넣을까”다. 한 세션에 전부 넣으면 AI가 서두르고, 쪼개면 각 세션이 자기 일만 본다.

사람은 코드 리뷰 병목에서 풀려나고, 대신 설계 의도와 평가 기준이라는 더 앞단에 시간을 쓴다.

관련

출처