처음 쓰던 방식
처음에는 작업이 생길 때마다 Claude Code에 "~해줘"라고 하나씩 요청했습니다. 원하는 걸 설명하면 Claude는 자기가 이해한 만큼으로 바로 구현을 시작했습니다. 설명이 추상적이면 이해한 내용도 추상적이었고, 다 만들어진 결과를 보고 나서야 제가 원한 것과 다르다는 걸 알았습니다. 그때부터 고치는 과정이 길어졌습니다. 왜 그렇게 만들었는지도 남지 않아서, 다음 세션에서 같은 판단을 처음부터 다시 하기도 했습니다.
전역 규칙: 4단계
그래서 모든 프로젝트에 적용되는 ~/.claude/CLAUDE.md에 작업 순서를 적었습니다.
- Specify: 요구사항, 제약, 성공 기준을 정합니다. 모호한 부분은 구현 전에 먼저 질문하게 했습니다.
- Plan: 접근 방식, 바꿀 파일, 대안을 검토합니다.
- Tasks: 계획을 따로 끝낼 수 있는 작업 단위로 나눕니다.
- Decisions: 고른 이유와 트레이드오프를 커밋 메시지와 주석에 남깁니다.
모든 작업에 네 단계를 다 거치면 작은 수정도 무거워집니다. 그래서 새 기능은 네 단계를 모두, 버그 수정은 Specify와 Decisions 위주로, 간단한 수정은 Specify만 하도록 기준을 같이 적었습니다.
프로젝트 규칙: 명세 먼저
사이드 프로젝트에서는 이 규칙을 더 구체적으로 만들었습니다. 기능마다 docs/features 아래에 한국어 명세를 먼저 쓰고, 이 문서를 정본으로 삼았습니다. 순서는 명세 → 구현 계획 → 서브에이전트 구현 → 코드 리뷰이고, 끝났다고 말하기 전에 qa:verify(포맷, 린트, 타입 체크, 빌드)를 통과해야 합니다.
실제 업무 프로젝트에는 같은 4단계를 스킬로 만들어 넣었습니다. 단계마다 그 단계에 필요한 참고 문서만 읽게 했고, 명세의 "영향받는 코드" 항목은 실제 검색 결과(파일:라인)로 채우게 했습니다. 단계가 끝날 때마다 제 승인을 받고 다음으로 넘어갑니다.
명세를 먼저 쓰니 구현을 시작하기 전에 제가 원하는 게 맞는지 검토하게 됐습니다. 명세를 읽다 보면 설명이 비어 있는 부분이 보였고, 그 부분을 채우면서 요구사항이 구체적으로 바뀌었습니다. 그다음 구현 방법을 정하고 구현을 맡기니, 결과물을 받은 뒤 왜 이렇게 구현됐는지 코드를 뜯어보는 시간이 줄었습니다. 앞 단계에 시간을 더 쓰는데도 전체 작업은 더 빨리 끝났습니다. 명세와 계획 문서는 사이드 프로젝트 두 곳에 합쳐서 180개 정도 쌓였습니다.
구현 전에 방향 확인하기
명세 외에도 구현을 맡기기 전에 방향을 맞추는 방법을 몇 가지 씁니다.
- 레이아웃 작업: 실제 컴포넌트를 만들기 전에 HTML로 화면을 빠르게 만들어 달라고 합니다. 브라우저로 열어 보고 방향이 맞는지 눈으로 확인한 뒤 구현을 시작합니다.
- 기획과 요구사항 분석: Claude와 대화하면서 제가 할 작업의 전체 흐름과 방향을 보고서 형식으로 정리하게 합니다.
- 이해가 안 되는 부분: 흐름이나 구조가 머리에 그려지지 않으면 다이어그램으로 그려 달라고 해서, 방향을 이해한 뒤에 구현을 요청합니다.
역할별 서브에이전트
한 세션이 명세부터 리뷰까지 다 하면, 자기가 만든 코드를 자기가 리뷰하게 됩니다. 그래서 역할을 나눈 서브에이전트를 만들었습니다.
| 서브에이전트 | 하는 일 | 코드 수정 |
|---|---|---|
| fe-spec-writer | 기능 명세 작성. 실행 중인 백엔드 Swagger를 직접 확인하고, 정하지 못한 것은 선택지와 추천안으로 남긴다 | 안 함 |
| fe-api-contract | 프론트 타입과 API 경로가 백엔드 계약과 맞는지 대조 | 안 함 |
| fe-implementer | 명세가 있을 때만 구현. 명세가 없으면 spec-writer를 먼저 쓰라고 돌려보낸다 | 함 |
| fe-test-author | 저장소의 테스트 방식에 맞춰 테스트 추가 | 함 |
| fe-reviewer | 변경 diff를 저장소 규약으로 검토. 체크리스트는 이 저장소에서 실제로 깨졌던 사례로 채웠다 | 안 함 |
| fe-design-reviewer | 브라우저로 모바일·태블릿·데스크톱 화면을 열어 디자인 문서 기준으로 검토 | 안 함 |
리뷰 역할은 모두 읽기 전용으로 두고, 발견한 것만 보고하게 했습니다.
세션 사이 인계
컨텍스트가 차기 전에 작업 상태를 인계 문서로 저장하고, 새 세션에서 그 문서를 읽어 이어갑니다. 지금까지 인계 문서가 100개 넘게 쌓였습니다. 스킬을 만든 과정은 Claude Code 스킬로 반복 작업 정리하기에 적었습니다.
쓰면서 고친 규칙
처음 만든 규칙을 그대로 쓰지는 못했습니다. 문제가 생길 때마다 규칙을 고쳤습니다.
- 서브에이전트 모델: 정의에 모델을 적지 않았더니 단순 대조 작업까지 전부 메인 세션의 큰 모델로 돌았습니다. 구현과 리뷰는 opus, 계약 대조와 테스트 보강은 sonnet으로 정의에 직접 적었습니다.
- 계획서 체크박스: 계획서 8개에 체크박스가 469개 있었는데 하나도 체크된 적이 없었습니다. 끝난 일도 미완료로 보여서 다음 세션이 상태를 잘못 읽었습니다. 계획서는 착수할 때의 기록으로만 두고, 진행 상황은 이슈와 PR을 기준으로 보기로 했습니다.
- 같은 작업 폴더: 두 세션이 같은 폴더에서 일하다가, 다른 세션이 고친 파일 16개가 제 커밋에 섞일 뻔했습니다.
git add -A와git stash를 금지하고 세션마다 워크트리를 따로 쓰게 했습니다. - 다른 프로젝트를 가리키는 서브에이전트: 한 프로젝트용 서브에이전트를 전역에 두었더니, 다른 프로젝트에서도 원래 프로젝트의 파일과 Swagger를 기준으로 일하려고 했습니다. 프로젝트 전용 서브에이전트는 그 저장소의
.claude/agents로 옮겼습니다. - Decisions 단계: 결정 기록용 폴더를 만들었지만 아직 비어 있습니다. 결정은 커밋 메시지와 인계 문서에만 남고 있습니다.
리뷰 지적을 실행해서 확인한 일
리뷰 서브에이전트의 지적을 그대로 받지 않은 일도 있었습니다. 스트리밍 응답 작업에서 리뷰가 "검증되지 않은 분기이니 토큰 재발급 분기를 지우자"고 했습니다. 가짜 백엔드를 띄워 실제로 돌려 보니 만료 토큰 → 401 → 재발급 → 200으로 정상 동작했습니다. 지적대로 지웠다면 동작하는 기능을 없앴을 겁니다.
반대로 리뷰가 실제로 잡은 것도 있었습니다. 린트 규칙이 검사하지 못하는 위치에서 계층 규약을 어긴 코드가 있었고, 문서 두 개가 같은 동작을 서로 다르게 설명하고 있었습니다. 지금은 리뷰 지적을 받으면 실행해서 확인할 수 있는 건 확인한 뒤에 반영합니다.
병렬로 나눠서 진행하기
화면 정리 작업을 레인 5개로 나눠 동시에 진행한 적이 있습니다. 목차 문서 하나와 레인별 문서를 두고, 레인마다 브랜치, dev 서버 포트, 손대도 되는 파일 범위, 착수 조건을 적었습니다. 여러 레인이 같이 쓰는 코드는 먼저 따로 올린 뒤에 레인을 시작했고, 머지는 제가 직접 했습니다.
충돌이 많이 나는 부분을 빼면 작업 속도는 혼자 순서대로 할 때보다 훨씬 빨랐습니다. 대신 세션과 서브에이전트가 늘어나는 만큼 토큰도 많이 씁니다. 앞에서 서브에이전트마다 모델을 나눠 적은 것도 이 때문인데, 병렬 작업에서는 각 세션이 읽는 문서와 파일 범위를 줄이는 방법까지 같이 고민해야 합니다.
지금의 작업 순서
- 요구사항이 모호하면 먼저 질문받고, 대화로 전체 흐름을 보고서 형식으로 정리합니다.
- 명세를 쓰고 승인합니다. 화면 작업이면 HTML 시안으로 방향을 먼저 확인합니다.
- 구현 계획을 쓰고, 계획대로 서브에이전트가 구현합니다.
- 리뷰 지적은 실행해서 확인한 뒤 반영합니다.
qa:verify를 통과하면 PR을 올리고, 머지는 직접 합니다.- 세션을 넘길 때는 인계 문서를 남깁니다.
다음에는 병렬 작업에서 토큰을 덜 쓰는 방법을 정리해 보려고 합니다. 각 세션에 꼭 필요한 문서만 넘기는 방식과, 서브에이전트에 맡길 일과 메인 세션이 할 일을 나누는 기준을 먼저 바꿔 볼 생각입니다.