오늘만 무료

Claude Code 멀티 에이전트 협업 설계

의사결정 로그·병렬 태스크 규칙·lessons.md로 같은 실수 반복제로

by AI개발자

8시간전 brunch_membership's

Coordination은 "Claude Code가 시간이 갈수록 더 잘하게 되는" 구조다

앞선 5개 장에서는 Claude Code가 안전하게, 오래, 혼자 작동하도록 만드는 구조였다.

이번에는 Coordination은 한 단계 더 나아간다.

"어제보다 오늘, 오늘보다 내일 Claude Code가 더 잘하게 만드는 구조."

단순히 실패를 막는 것이 아니라, 실패에서 학습하고, 결정 근거를 남기고, 여러 인스턴스가 충돌 없이 협업하는 구조를 만든다.

하나의 Claude Code로 할 수 있는 것에는 한계가 있다. 조사·구현·리뷰를 병렬로 처리하거나, 지난 세션의 교훈을 다음 세션에 자동으로 적용하려면 에이전트 간의 조율 구조가 필요하다.

체크 18: 중요한 의사결정을 반드시 기록하고 경고한다

어떤 일이 벌어졌나

Claude Code가 "변경 사항을 프로덕션 서버에 반영하겠습니다"라고 말하며 git push origin main

을 실행했다. 배포 후 서비스 장애가 발생했다.

사후 분석을 위해 로그를 열었다. activity-log.jsonl에는 명령 실행 기록이 있었지만, "왜 그 시점에 프로덕션에 직접 push했는지"에 대한 근거가 어디에도 없었다.

Claude Code가 어떤 판단 근거로 그 결정을 내렸는지 추적할 수 없었다.

왜 이런 일이 생기나

Claude Code는 명령을 실행하지만, "왜 이 결정을 내렸는가"를 별도로 기록하지 않는다. activity-log.jsonl은 "무엇을 했는가"는 기록하지만, "왜 했는가"는 담지 않는다.

되돌릴 수 없는 조작이 실행되기 직전에 결정 이유를 별도 파일에 강제로 기록하는 구조가 필요하다.

해결책: decision-warn.sh로 중요 조작 전 감사 로그 자동 생성

1단계. hook 스크립트를 배치한다.

curl -o ~/.claude/hooks/decision-warn.sh \

https://raw.githubusercontent.com/gaebalai/claude-code-hooks/main/hooks/decision-warn.sh

chmod +x ~/.claude/hooks/decision-warn.sh

2단계. PreToolUse hook에 추가한다.

{

"hooks": {

"PreToolUse": [

{

"matcher": "Bash",

"hooks": [

{ "type": "command", "command": "bash ~/.claude/hooks/branch-guard.sh" },

{ "type": "command", "command": "bash ~/.claude/hooks/error-gate.sh" },

{ "type": "command", "command": "bash ~/.claude/hooks/no-ask-human.sh" },

{ "type": "command", "command": "bash ~/.claude/hooks/decision-warn.sh" }

]

}

]

}

3단계. hook이 감지하는 조작과 기록 형식을 확인한다.

# decision-log.jsonl에 기록되는 예시

[DECISION] Bash: git push origin main

→ Reason: deployment to production

→ Logged to: ~/.claude/decision-log.jsonl

{

"ts": "2026-03-01T14:32:00Z",

"type": "DECISION",

"tool": "Bash",

"command": "git push origin main",

"reason": "chapter-5 작성 완료 후 배포",

"reversible": false,

"logged_to": "~/.claude/decision-log.jsonl"

}

hook이 경고 로그를 남기는 조작 유형:

decision-log.jsonl 활용법:

# 오늘 내려진 모든 중요 결정 조회

jq 'select(.type == "DECISION")' ~/.claude/decision-log.jsonl | \

jq 'select(.ts | startswith("2026-03-01"))'

# 되돌릴 수 없는 조작만 필터링

jq 'select(.reversible == false)' ~/.claude/decision-log.jsonl

# 특정 명령의 결정 이력 조회

jq 'select(.command | contains("git push"))' ~/.claude/decision-log.jsonl

� 장애 대응 시 활용: 서비스 장애가 발생했을 때, decision-log.jsonl을 열면 장애 시점 전후로 어떤 결정이 내려졌는지 시간순으로 파악할 수 있다. "언제, 무엇을, 왜 했는지"가 모두 기록되어 있어 근본 원인 분석(RCA) 시간을 크게 줄일 수 있다.

� 한국 규제 환경 참고: 금융·의료·개인정보를 다루는 서비스는 감사 로그(audit trail) 보존 의무가 있다. decision-log.jsonl을 S3 또는 NAS에 정기적으로 백업하면 컴플라이언스 요구사항 충족에도 활용할 수 있다. AWS S3 서울 리전(ap-northeast-2)에 자동 업로드하는 간단한 cron 예시:

# crontab -e 에 추가

0 2 * * * aws s3 cp ~/.claude/decision-log.jsonl \

s3://내버킷/claude-logs/$(date +%Y-%m-%d)-decision-log.jsonl \

--region ap-northeast-2

체크 19: 병렬 태스크 규칙으로 파일 충돌을 방지한다

어떤 일이 벌어졌나

속도를 높이기 위해 두 개의 Claude Code 세션을 동시에 실행했다. 하나는 API 응답 형식을 조사하고, 다른 하나는 그 결과를 바탕으로 파싱 코드를 작성하는 역할이었다.

그런데 두 세션 모두 src/api/parser.ts를 수정했다. 나중에 완료된 세션이 먼저 완료된 세션의 변경을 덮어썼다. 한쪽의 2시간 작업이 흔적도 없이 사라졌다.

왜 이런 일이 생기나

Claude Code는 다른 인스턴스가 동시에 같은 파일을 수정하고 있는지 인식하지 못한다. 각 세션은 자신의 컨텍스트 안에서 독립적으로 판단하고 행동한다.

병렬 실행 전에 "누가 어떤 파일을 담당하는지"를 명확히 분리하고, 충돌 가능성이 있는 작업은 순차 실행으로 강제하는 규칙이 필요하다.

해결책: CLAUDE.md에 병렬 태스크 분류 규칙을 명시

## 병렬 태스크 규칙

### 병렬 실행 가능한 태스크

- 파일을 **읽기만** 하는 조사·분석 (쓰기 없음)

- **서로 다른 디렉터리**의 파일에 각자 독립적으로 작성

- **독립적인** 외부 API 호출 (결과가 서로에게 영향 없음)

- 단위 테스트 실행 (파일 변경 없음)

- 문서 생성 (새 파일 생성, 기존 파일 수정 없음)

### 반드시 순차 실행해야 하는 태스크

- **같은 파일**에 두 인스턴스가 모두 쓰기를 수행하는 경우

- **DB 마이그레이션** (스키마 변경은 항상 순차 실행)

- **배포 조작** (CI/CD 파이프라인 실행, 서버 재시작 등)

- 한 태스크의 출력이 다른 태스크의 **입력이 되는** 경우

- **공유 설정 파일** 수정 (package.json, tsconfig.json, .env 등)

### 병렬 실행 시 서브에이전트 지시 규칙

서브에이전트를 띄울 때는 반드시 아래를 명시한다:

```markdown

# 서브에이전트 지시 템플릿

## 담당 범위

- 접근 허용 파일/디렉터리: [명시]

- 접근 금지 파일/디렉터리: [명시]

## 완료 조건

- [구체적인 완료 기준]

## 보고 방법

- 완료 시 ~/ops/task-queue.yaml 의 해당 태스크 status를 done으로 업데이트

- 이슈 발생 시 ~/ops/pending_for_human.md 에 기록

```

� 모노레포 환경에서의 병렬 실행: packages/ 하위의 각 패키지 디렉터리가 독립적이라면 패키지 단위로 병렬 실행이 가능하다. 단, 루트의 package.json, turbo.json, .eslintrc 등 공유 설정 파일은 반드시 순차 처리해야 한다. 병렬 실행 전 "공유 파일 목록"을 CLAUDE.md에 명시해 두면 충돌 위험을 크게 줄일 수 있다.

이 분류를 CLAUDE.md에 명시한 이후, 병렬 실행 시 파일 충돌이 완전히 사라졌다.

체크 20: lessons.md로 같은 실수를 두 번 다시 반복하지 않는다

어떤 일이 벌어졌나

지난번 세션에서 특정 문제 해결에 2시간을 소비했다.

이번 주 새 세션에서 완전히 똑같은 문제가 다시 발생했다. 이전 세션의 교훈이 새 세션에 전달되지 않았기 때문이다. 결국 또 2시간을 소비했다.

총 4시간. 같은 문제에 두 번이나 발생했다.

왜 이런 일이 생기나

Claude Code는 세션 간에 기억을 이어받지 않는다. 지난 세션에서 어떤 문제를 겪었는지, 어떻게 해결했는지는 새 세션에서 처음부터 다시 발견해야 한다.

해결책을 외부 파일에 기록해 두고, 세션 시작 시 반드시 읽도록 하면 이 망각 문제를 구조적으로 해결할 수 있다.

해결책: lessons.md로 교훈을 영속적으로 축적

1단계. lessons.md 파일을 만든다.

touch ~/ops/lessons.md

2단계. 문제가 발생할 때마다 아래 형식으로 기록한다.

# ~/ops/lessons.md

## 2026-03-01 X(트위터) 예약 발행의 React select 상태 미반영

**증상**

select 값을 변경해도 React state에 반영되지 않는다.

**원인**

React가 `value`를 State로 관리하기 때문에, Puppeteer 등으로 DOM을 직접 조작해도

React의 내부 상태는 변경되지 않는다. React는 실제 DOM 변경을 감지하지 않는다.

**해결책**

React UI를 직접 조작하려 하지 말 것.

오늘 발행 건수가 0건이면 예약 대신 즉시 발행으로 전환한다.

**재발 방지**

예약 발행은 전날 미리 설정한다. 당일 설정은 시도하지 않는다.

---

## 2026-02-27 REST API PUT 요청 시 기존 데이터 전체 소실

**증상**

PUT 요청을 보냈더니 기존에 저장된 데이터가 전부 사라졌다.

**원인**

GET 없이 PUT 했기 때문에, 업데이트하려는 필드 외의 모든 필드가 빈 값으로 덮어씌워졌다.

많은 REST API가 PUT을 "전체 교체"로 처리한다.

**해결책**

PUT 전에는 반드시 GET → 기존 데이터와 병합 → PUT의 3단계를 거친다.

부분 업데이트가 필요하면 PUT 대신 PATCH를 사용한다.

**재발 방지**

API 문서에 명시되지 않은 경우, PUT은 항상 전체 교체로 간주한다.

이 규칙을 CLAUDE.md에도 추가해 둔다.

---

## 2026-02-25 GitHub Actions 환경변수 미설정으로 CI 실패

**증상**

로컬에서는 정상 작동하지만 CI에서만 실패한다.

**원인**

로컬 `.env`에는 있지만 GitHub Actions Secrets에는 추가하지 않은 환경변수를 참조하고 있었다.

**해결책**

GitHub 레포지토리 Settings → Secrets and variables → Actions에서 해당 키를 추가한다.

**재발 방지**

새 환경변수를 추가할 때는 로컬 `.env`, GitHub Secrets, 배포 서버 환경변수를 동시에 업데이트한다.

체크리스트로 관리한다: `~/ops/dod-checklists.md`의 "환경변수 추가 DoD"에 항목 추가 완료.

3단계. CLAUDE.md에 세션 시작 시 lessons.md 참조 규칙을 추가한다.

## 세션 시작 시 필수 참조 파일 (순서대로)

1. ~/ops/mission.md → 현재 전체 맥락 파악

2. ~/ops/task-queue.yaml → 오늘 할 작업 목록 확인

3. ~/ops/lessons.md → 과거 실수와 해결책 확인

lessons.md를 읽지 않고 작업을 시작하지 말 것.

같은 실수를 반복하지 않는 것이 최우선이다.

## lessons.md 업데이트 규칙

아래 상황이 발생하면 반드시 lessons.md에 기록한다:

- 예상보다 30분 이상 걸린 문제 해결

- 같은 에러를 2회 이상 마주친 경우

- 공식 문서와 실제 동작이 다른 것을 발견한 경우

- 특정 API·라이브러리의 예상치 못한 동작을 발견한 경우

기록 형식: 증상 → 원인 → 해결책 → 재발 방지 (4개 항목 필수)

� lessons.md가 쌓일수록 무슨 일이 생기나: 처음에는 단순 메모처럼 보이지만, 30개 이상의 항목이 쌓이면 패턴이 보인다. 예를 들어 "외부 API 관련 실수가 많다"면 API 호출 전 검증 로직을 강화해야 한다는 신호다. "로컬과 CI 환경 차이로 인한 실수가 반복된다"면 환경 일치 전략을 CLAUDE.md에 추가해야 한다. lessons.md는 단순한 로그가 아니라 Claude Code 운영 노하우의 집약본이 된다.