클로드 코드 서브에이전트 완전정복 (총 9편) | 6편 ADR/RFC/설계서 작성 자동화 — 역할별 운영 템플릿과 실전 가이드

시리즈: 클로드 코드 서브에이전트 완전정복 (총 9편) | 6편

ADR/RFC/설계서 작성 자동화 — 역할별 운영 템플릿과 실전 가이드

ADR이나 RFC 같은 설계 문서를 서브에이전트로 자동화하고 싶은데 역할을 어떻게 나눠야 할지 막막하신가요? 이 글에서는 스코퍼부터 반박자까지 7가지 역할 템플릿과 권한 설정, 입출력 계약, 확장 ADR 양식까지 실전에 바로 쓸 수 있게 한 번에 정리했어요.

Summary

• ADR/RFC 작성에는 7가지 역할(스코퍼~코디네이터)을 서브에이전트로 분리해요
• 각 역할마다 허용 도구와 입출력 계약을 명확히 정의해야 해요
• RFC에서는 "반박자" 역할을 독립시키고, 반대 근거 찾기를 성공 조건으로 두는 게 핵심이에요
• ADR 확장 템플릿에 Evidence, Validation Plan, Audit Log를 추가하면 품질이 크게 올라가요

이 글의 대상

• ADR이나 RFC를 팀에서 쓰고 있지만 작성이 번거로운 분
• 설계 문서 작성을 서브에이전트로 자동화해 보고 싶은 분
• 역할별로 에이전트를 나누는 구체적인 방법이 궁금한 개발자

목차

1. ADR/RFC에 서브에이전트가 필요한 이유
2. 7가지 역할 — 누가 뭘 하는가
3. 역할별 권한 기본값
4. 역할별 입출력 계약 상세
5. ADR 확장 템플릿
6. RFC에서 반박자 역할이 특별한 이유
7. 실전 운영 흐름

---

1. ADR/RFC에 서브에이전트가 필요한 이유

ADR(Architecture Decision Record)이나 RFC(Request for Comments)는 단순 문서가 아니에요. 기술적 의사결정의 근거, 대안, 검증 계획까지 담아야 하는 구조화된 의사결정 기록이에요.

한 사람이 혼자 쓰면 이런 문제가 생겨요:

• 자기가 선호하는 대안에 편향된 근거만 수집
• 반대 의견을 형식적으로만 다루고 넘어감
• 보안이나 규정 검토를 빠뜨림

서브에이전트로 역할을 분리하면 각 단계에서 독립적인 관점이 반영되니까 문서의 객관성과 완성도가 올라가요.

---

2. 7가지 역할 — 누가 뭘 하는가

ADR/RFC 작성에 활용할 수 있는 역할은 크게 7가지예요.

순서	역할	한줄 설명
1	스코퍼	문서의 범위와 핵심 질문을 정의해요
2	소스 파인더	1차/2차 출처를 수집해요
3	요약자	수집된 출처를 요약하고 인용을 준비해요
4	작성자(Writer)	템플릿에 맞춰 초안을 작성해요
5	반박자/검증자	사실 검증, 환각 탐지, 반대 근거를 찾아요
6	편집자	템플릿 형식과 문체를 통일해요
7	정책/보안 검토자	규정 준수와 보안 이슈를 점검해요

여기에 전체를 조율하는 코디네이터(오케스트레이터)가 있어요. 코디네이터는 별도 서브에이전트이거나 메인 에이전트가 직접 수행할 수도 있어요.

모든 역할을 다 써야 하는 건 아니에요. 팀 규모와 문서 중요도에 따라 3~4개만 골라 쓸 수도 있어요.

---

3. 역할별 권한 기본값

각 역할이 어떤 도구를 쓸 수 있는지 기본값을 정리했어요.

역할	허용 도구	Write 허용	특이사항
스코퍼	Read, Task	X	범위 정의만, 자료 수집은 안 함
소스 파인더	Web, Read, Grep, Glob	X	읽기 전용, 절대 Write 금지
요약자	Read	X	수집된 자료만 읽고 정리
작성자	Read, Write, Edit	O (초안만)	자동 커밋/배포는 금지
반박자/검증자	Read, Task	X	추가 조사 가능, 수정은 불가
편집자	Read, Write, Edit	O (형식 수정)	diff 형태로 반환 권장
정책/보안 검토자	Read	X	고위험 발견 시 승인 목록 생성
코디네이터	Task	X	오케스트레이션만, 직접 작업 안 함

핵심 원칙은 최소 권한이에요. 읽기만 하면 되는 역할한테 Write를 주면 안 돼요. 4편에서 다뤘던 도구 경계와 같은 맥락이에요.

---

4. 역할별 입출력 계약 상세

각 역할이 뭘 받아서 뭘 내보내는지, 구체적인 계약을 정리해 볼게요.

스코퍼

• 입력: 의사결정 주제, 배경 문맥
• 출력: 범위 정의서 (다루는 것 / 안 다루는 것), 핵심 질문 목록
• 도구: Read (기존 문서 확인), Task (관련 컨텍스트 탐색)

스코퍼가 범위를 잘 잡아야 이후 단계에서 삽질을 줄일 수 있어요. "이 ADR에서 답해야 할 질문"을 명확히 정의하는 게 핵심이에요.

소스 파인더

• 입력: 스코퍼가 정의한 핵심 질문 목록
• 출력: 출처 목록 (1차 출처 + 2차 출처), 각 출처의 관련성 요약
• 도구: Web, Read, Grep, Glob

1차 출처(공식 문서, 논문)와 2차 출처(블로그, 토론)를 구분해서 수집해요. 신뢰도 레이블을 붙여두면 이후 단계에서 활용하기 편해요.

요약자

• 입력: 소스 파인더가 수집한 출처 목록
• 출력: 출처별 요약 + 인용 가능한 형태로 가공된 데이터
• 도구: Read

인용 형식을 통일하는 게 중요해요. "출처 A에 따르면 [claim]. (URL, 접근일)" 같은 패턴으로 정리해 두면 작성자가 바로 가져다 쓸 수 있어요.

반박자/검증자

• 입력: 작성자가 만든 초안
• 출력: 검증 보고서 (사실 오류, 논리 비약, 누락된 대안, 환각 탐지 결과)
• 도구: Read, Task (추가 조사)

이 역할은 "문제를 찾는 것"이 성공이에요. 문제를 못 찾으면 검증이 부족한 거지, 문서가 완벽한 게 아니에요.

편집자

• 입력: 검증 완료된 초안
• 출력: 형식/문체 통일된 최종 초안 (diff 형태 권장)
• 도구: Read, Write, Edit

편집자는 내용을 바꾸면 안 돼요. 템플릿 형식 맞추기, 용어 통일, 문체 교정만 해요. 내용 수정이 필요하면 작성자한테 돌려보내야 해요.

정책/보안 검토자

• 입력: 편집 완료된 문서
• 출력: 규정 준수 체크리스트 + 보안 이슈 목록 (고위험 항목은 승인 목록)
• 도구: Read

고위험 발견이 있으면 "이 항목은 보안팀 승인이 필요하다"는 승인 목록을 만들어요. 이게 최종 Human 승인 단계에서 반드시 확인해야 할 항목이 되는 거예요.

---

5. ADR 확장 템플릿

기본 ADR 템플릿(Title, Status, Context, Decision, Consequences)에 서브에이전트 파이프라인에 맞는 확장 섹션을 추가할 수 있어요.

# ADR-NNN: [제목]

## Status
[Proposed | Accepted | Deprecated | Superseded]

## Context
[의사결정이 필요한 배경과 제약조건]

## Decision
[선택한 결정과 그 이유]

## Consequences
[예상되는 긍정적/부정적 결과]

---
# 확장 섹션 (서브에이전트 파이프라인용)

## Evidence
| 주장 (Claim) | 근거 (Evidence) | 출처 | 신뢰도 |
|-------------|----------------|------|--------|
| ... | ... | ... | 높음/중간/낮음 |

## Alternatives
| 대안 | 장점 | 단점 | 탈락 사유 |
|------|------|------|----------|
| ... | ... | ... | ... |

## Validation Plan
- [ ] 검증 항목 1: ...
- [ ] 검증 항목 2: ...
- [ ] 예상 검증 시점: ...

## Audit Log
| 시점 | 단계 | 담당 에이전트 | trace_id | 결과 |
|------|------|-------------|----------|------|
| ... | Research | source-finder | trace-abc | 출처 5건 수집 |
| ... | Verify | critic | trace-def | 이슈 2건 발견 |
| ... | Approve | human (jayden) | - | 승인 |

Evidence 섹션이 핵심이에요. 모든 주장에 근거를 매핑하면 나중에 "왜 이렇게 결정했지?"라는 질문에 바로 답할 수 있어요.

Audit Log는 5편에서 다뤘던 관측가능성을 문서 안에 직접 녹인 거예요. 어떤 에이전트가 어떤 단계에서 뭘 했는지 기록이 남으니까 문제가 생겼을 때 역추적이 가능해요.

---

6. RFC에서 반박자 역할이 특별한 이유

RFC는 ADR과 다르게 "의견을 구하는" 문서예요. 그래서 반대 의견을 적극적으로 찾는 게 문서의 가치를 높여요.

반박자(Critic) 역할을 독립시키고, "반대 근거 찾기"를 성공 조건으로 설정하는 게 핵심이에요.

반박자 성공 조건 예시:
- 제안된 설계의 약점을 최소 3개 이상 식별했는가?
- 각 약점에 대한 근거(기술적 사례, 연구, 사례)를 제시했는가?
- 대안이 더 나을 수 있는 시나리오를 최소 1개 이상 제시했는가?

이렇게 하면 반박자가 "문제없어요"로 끝나는 게 아니라 적극적으로 약점을 파헤쳐요. RFC에 포함된 반대 의견이 탄탄하면 리뷰어들이 이미 고려된 사항을 중복으로 지적하는 일이 줄어들어서 전체 리뷰 시간도 단축돼요.

RFC 요소	반박자 없을 때	반박자 있을 때
반대 의견	리뷰어가 떠올려야 함	문서에 이미 포함
대안 분석	형식적, 피상적	구체적 시나리오 포함
리뷰 시간	길어짐 (같은 지적 반복)	단축됨 (이미 다뤘으니까)
의사결정 품질	편향 가능성 높음	다각적 검토 완료

---

7. 실전 운영 흐름

실제로 ADR 하나를 서브에이전트 파이프라인으로 만드는 흐름을 정리해 볼게요.

Step 1: 코디네이터 → 스코퍼에게 주제 전달
Step 2: 스코퍼 → 범위 정의 + 핵심 질문 목록 반환
Step 3: 코디네이터 → 소스 파인더에게 질문 목록 전달
Step 4: 소스 파인더 → 출처 목록 반환
Step 5: 요약자 → 출처 요약 + 인용 준비
Step 6: 작성자 → ADR 확장 템플릿에 맞춰 초안 작성
Step 7: 반박자 → 검증 보고서 반환
Step 8: (이슈 있으면) 작성자 → 수정
Step 9: 편집자 → 형식/문체 통일
Step 10: 정책/보안 검토자 → 규정/보안 점검
Step 11: Human → 최종 승인
Step 12: (승인 시) 커밋/병합

처음에는 이 전체 흐름이 복잡해 보일 수 있어요. 하지만 한 번 설정해 두면 이후에는 주제만 바꿔서 재사용할 수 있어요. 파이프라인이 팀의 자산이 되는 거죠.

시작할 때는 스코퍼 → 소스 파인더 → 작성자 → 반박자 → Human 5단계로 줄여서 시작하고, 익숙해지면 나머지 역할을 추가하는 걸 추천해요.

---

핵심 정리

1. ADR/RFC 작성에는 최대 7가지 역할을 서브에이전트로 분리할 수 있다
2. 모든 역할의 기본 원칙은 최소 권한 — Write가 필요 없으면 주지 마라
3. RFC에서는 반박자를 독립시키고 "반대 근거 찾기"를 성공 조건으로 둬라
4. ADR 확장 템플릿(Evidence, Audit Log)으로 추적성과 객관성을 확보하라
5. 처음에는 5단계로 시작하고 점진적으로 역할을 추가하라

---

FAQ

Q. ADR이 뭔지 잘 모르는데, 서브에이전트 없이도 쓸 수 있나요?

A. 물론이에요. ADR은 "왜 이 기술적 결정을 내렸는가"를 기록하는 짧은 문서예요. 서브에이전트 없이 사람이 직접 써도 되고, 그게 더 익숙하다면 그렇게 시작하는 게 좋아요. 서브에이전트는 ADR 작성이 반복적이고 양이 많아졌을 때 자동화하는 도구예요.

Q. 7가지 역할을 다 써야 하나요? 역할이 너무 많은 것 같은데요.

A. 아니에요. 팀 규모와 문서 중요도에 따라 3~5개만 골라 쓰면 돼요. 소규모 팀이라면 소스 파인더 + 작성자 + 반박자 + Human 4가지만으로도 충분해요. 역할을 다 쓰는 건 대규모 조직이나 규제가 엄격한 환경에서예요.

Q. 반박자가 찾은 약점을 작성자가 무시하면 어떻게 하나요?

A. 워크플로에 "반박자 이슈 해소 게이트"를 넣어두면 돼요. 반박자가 제기한 이슈 각각에 대해 "수용(수정함)", "반박(이유와 함께 기각)", "보류(추후 검토)" 중 하나를 택하도록 하면 무시가 구조적으로 불가능해져요.

Q. Audit Log에 trace_id를 남기면 나중에 실제로 활용할 수 있나요?

A. 네. trace_id가 있으면 "이 Evidence는 어떤 리서치 세션에서 수집됐지?"를 역추적할 수 있어요. 특히 의사결정에 문제가 생겨서 원인을 파악해야 할 때 정말 유용해요. 없으면 처음부터 다시 조사해야 하거든요.

Q. 정책/보안 검토자 역할은 소규모 프로젝트에서도 필요한가요?

A. 개인 프로젝트나 사이드 프로젝트에서는 생략해도 돼요. 하지만 팀 프로젝트에서 인프라 변경, 인증 방식 변경, 데이터 처리 방식 변경 같은 결정을 기록할 때는 가벼운 보안 체크리스트라도 넣어두는 게 좋아요.

Q. ADR 확장 템플릿의 Evidence 섹션에 신뢰도를 어떻게 매기나요?

A. 간단한 기준으로 시작하면 돼요. 공식 문서/논문은 "높음", 기술 블로그/토론은 "중간", 개인 의견/경험담은 "낮음" 정도로 분류해요. 완벽할 필요 없이 대략적인 구분만 있어도 의사결정 시 근거의 무게를 판단하는 데 도움이 돼요.

Q. 기존에 쓰던 ADR 템플릿이 있는데, 확장 섹션만 추가하면 되나요?

A. 네, 그게 가장 좋은 방법이에요. 기존 템플릿(Title, Status, Context, Decision, Consequences)은 그대로 두고 아래에 Evidence, Alternatives, Validation Plan, Audit Log를 추가하면 돼요. 기존 작업 흐름을 깨지 않으면서 점진적으로 개선할 수 있어요.

---

참고 자료 (References)

데이터 출처

출처	설명	링크
ADR GitHub	ADR 표준 템플릿과 가이드	adr.github.io
Claude Code 서브에이전트 문서	서브에이전트 정의 및 설정	code.claude.com
Claude Code Agent Teams	멀티 에이전트 팀 구성	code.claude.com

핵심 인용

"An architecture decision record is a short text file describing a specific architecture decision. We keep a collection of ADRs in a decision log."
— Michael Nygard, adr.github.io

---

다음 편 예고

[7편] 서브에이전트 운영의 7가지 실패 모드와 예방법

• 컨텍스트 오염, 권한 과다, 무한 루프 등 실전에서 만나는 실패 패턴
• 각 실패 모드의 증상, 원인, 예방법을 하나씩 짚어보기
• "잘 설계했는데 왜 안 되지?"의 답을 찾는 트러블슈팅 가이드