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

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

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 에 추가