CCAR-P 개념 카드

■ ADR·아키텍처 패키지

architecture decision record — 결정·맥락·기각 대안 · 재논쟁 방지6.4 본편

표시가 없는 문장은 공식 문서에서 확인한 내용이에요. 다른 표시는 읽는 법

왜 배우나 — 시험이 요구하는 것

시험 목표 6.4 구조 문서화 · D6 사람·문서 14%
Document architectures and provide implementation guidance

이 개념으로 푸는 판단 (할 수 있어야 하는 것)

  • 6.4① 몇 달 뒤 팀이 "왜 RAG 로 했지?" 를 처음부터 다시 논쟁한다 — 인계 때 무엇이 빠졌나? (빈 목표) — 결정 기록(ADR)과 아키텍처 패키지의 목적
  • 6.4③ ADR 에 "100쪽 계약은 context rot 때문에 RAG" 라고 적었다 — 이 근거가 맞나? — ADR 근거를 공식 기준·평가 증거로 적기 (크기 기준부터 확인)

한눈에

결정마다 한 장씩 세 가지를 남긴다.

  • 무엇을 골랐나?
  • 왜 골랐나? (맥락·제약·증거)
  • 무엇을 버렸나? (기각된 대안과 이유)

목적은 사람이 바뀌어도 정해진 trade-off(절충)가 다시 논쟁되지 않게 하는 것이다 업계 일반 ADR 양식은 Anthropic 문서 없음, 양식 암기보다 목적

공식 문서에서 가장 가까운 원칙은 코드에서 못 읽는 것만 적는 것이다. 프로젝트 고유의 구조 결정은 넣고, 코드를 읽으면 알 수 있는 것은 뺀다 (Claude Code CLAUDE.md 규칙이다. 사람 팀 문서로 넓힌 것은 추론이다)

비유 "왜 EKS 대신 ECS 인가" 를 남긴 인프라 결정 기록과 같다. 기록이 없으면 새 팀원마다 같은 논쟁을 한다. "Slack 스레드에 다 있다" 가 속이는 습관이다

코드와 프롬프트에는 무엇만 남고, ADR 한 장에 결정·맥락·기각 대안을 적어 코드 옆 레포에 두면 정해진 절충이 다시 논쟁되지 않는다.
그림으로 보기 (AI 생성 · Codex · 누르면 크게)

ELI5

이사 가면서 새 집주인에게 "왜 이 벽에 선반을 달았는지" 쪽지를 남기는 거예요.

  • 선반은 눈에 보여요. 그런데 "왜 여기에 달았는지"는 안 보여요.
  • 쪽지가 없으면 새 주인은 벽을 다시 재고, 같은 고민을 처음부터 해요.
  • 쪽지에는 "다른 벽은 습기가 차서 안 됐어요"처럼 버린 자리도 적어요.
  • 집이 바뀌면(벽을 새로 바르면) 쪽지도 새로 써요.

개념 설명

영상 — 결정의 '왜'는 어디에 남길까? (약 43초 · 소리 없음 · 자막). 쪽지 값(계약 1건 ≈ 3만 토큰 · 기각 RAG)은 카드 흐름 ① · '석 달 뒤/1년 뒤' · 팀원 3명 · 메모 4장은 그림용 가정(실측 아님) · '코드로 못 읽는 것만 적는다' 는 Claude 가 읽는 문서(CLAUDE.md) 원칙을 사람 팀 기록에 옮긴 추론(설명 미해결 2) 작은 화면에서는 전체화면(⛶)으로 보세요.

원리

ADR (architecture decision record) 한 장

  • 결정 · 맥락(문제·제약·위험·증거) · 기각된 대안과 이유를 적는다. 양식(제목·상태·결과 칸)은 업계 일반이고 Anthropic 문서에 없다. 그래서 시험은 양식보다 목적(재논쟁 방지)을 물을 것으로 본다.
  • 코드는 "무엇"을 보여 준다. 그러나 "왜"와 "채택 안 한 대안"은 보여 주지 않는다. 사람이 바뀌면 그것이 사라진다. 그래서 새 팀이 처음부터 다시 비교한다.

공식에서 가장 가까운 원칙 (Claude Code 가 읽는 문서, CLAUDE.md)

  • 넣을 것은 프로젝트 고유의 구조 결정과 흔한 함정이다. 뺄 것은 코드를 읽으면 알 수 있는 것이다.
  • /doctor 는 구조 개요·디렉터리 배치처럼 코드로 알 수 있는 것은 자르고, 함정·이유(rationale)는 남긴다.
  • 줄마다 "지우면 실수가 나나?" 를 묻는다. 아니면 뺀다. 길면 중요한 규칙이 묻힌다.
  • 코드처럼 다룬다.
    • 일이 틀어지면 검토한다.
    • 주기적으로 쳐낸다.
    • git 에 넣어 팀이 기여하게 한다.
    • 시간이 갈수록 쓸모가 쌓인다.
  • 이 원칙들은 Claude 가 읽는 문서 기준이다. 사람 팀의 결정 기록에 그대로 옮긴 것은 추론이다.

근거는 평가 증거

  • 공식 출발점은 성공 기준(success criteria)을 정하고 평가를 설계하는 것이다. 평가가 있으면 숫자가 짐작을 대신한다.
  • 그래서 ADR 의 "왜" 칸은 "좋아 보여서"가 아니라 평가셋 숫자(품질·지연(latency)·비용)로 채운다.
  • 근거 문장이 공식 기준과 어긋나면 기록이 있어도 틀린 결정이 굳는다. 6.4③ 의 "context rot 이니 RAG" 가 그런 예다. 크기를 먼저 본다(◆ RAG vs full context).

아키텍처 패키지

  • 아키텍처 패키지는 아래 문서로 이루어진다. 구성은 업계 일반이다(목록 6.4①).
    • ADR 묶음
    • 흐름 그림(입력, 처리, 출력, feedback loop)
    • 고른 패턴과 이유
    • 모델 선택과 평가 근거
    • 가드레일·규정
    • 평가·모니터링 계획
  • 패턴 이름은 가이드 기준 3개다. workflow · agentic · augmented LLM 이다.
  • ADR 은 패키지 전체가 아니다. 구현 가이드·런북은 ■ 구현 가이드 에 있다.

규칙과 판단

코드에서 읽히지 않는 결정은 회의록이 아니라 코드 옆 레포의 ADR 로 남기고, 전제가 바뀌면 옛 ADR 을 지우지 않고 새 ADR 로 대체한다.
그림으로 보기 (AI 생성 · Codex · 누르면 크게)

갈림길

①⑤ 인계 때 무엇을 [6.4①]

코드에서 읽히나?파일 구조·API 목록 vs 왜·채택 안 한 대안
예

적지 않는다

코드를 읽으면 알 수 있는 것은 뺀다

아니오
어디 두나?
회의록·채팅

흩어진다

기록이 흩어져 새 팀이 못 찾는다 업계 일반

코드 옆 레포

ADR 로 남긴다

결정 · 맥락 · 기각된 대안과 이유를 남긴다 업계 일반. 공식 문서는 CLAUDE.md 를 git 에 넣어 팀이 기여하게 하라고 한다

② 근거 쓰기 [6.4①] [6.4③]

결정 근거·이유가 무엇으로 적혔나?
평가셋 숫자

그대로 적는다

성공 기준(success criteria)과 평가셋 숫자(품질·지연(latency)·비용)를 적는다

일반론 ('context rot 이니 RAG')

공식 기준부터 대조한다

근거 문장 자체가 공식 기준과 맞는지 확인한다. 자세한 것은 ◆ RAG vs full context 에 있다 (크기 먼저)

패턴 이름만 (이유가 없다)

패턴과 이유를 적는다

고른 패턴과 이유를 적는다. 패턴은 workflow · agentic · augmented LLM 중 하나다

④ 다시 열까 [6.4①]

전제가 바뀌었나?데이터 크기·모델·가격·요구
아니오

기록대로 간다

재논쟁 없이 ADR 을 가리킨다 업계 일반

예

새 ADR 로 대체한다

옛 것은 지우지 않고 대체됨으로 표시한다 업계 일반. 새 모델이면 평가셋으로 다시 확인한다

흐름

그림 속 이름·금액·시간·토큰 수는 예시예요. 공식 한도·동작은 카드 본문 값이 기준.

장면 글로 보기

칸 : 아키텍트 → 인계 문서 → 새 팀

블록 : 결정, 맥락·증거 (바뀌는 것), 기각 대안 (바뀌는 것), 코드·프롬프트

질문 : 새 팀은 "왜" 를 어디서 알까?

① ADR 로 인계 ✓

  1. 시작 : 아키텍트 — 쪽지 : 결정: 계약서 / full context + 캐싱
  2. 기록 : 결정 → 인계 문서 : 결정·맥락·기각 대안을 적는다 — 쪽지 : ADR-007 / full context + 캐싱 / 맥락: 계약 1건 ≈ 3만 토큰 / 기각: RAG (20만 미만)
  3. 읽기 : 인계 문서 → 새 팀 : 재논쟁 없이 ADR 을 가리킨다 — 말 : “RAG 는 ADR-007 에서 이미 기각됐네요.”
  4. 끝 : 정해진 trade-off 가 다시 논쟁되지 않는다

② 코드·프롬프트만 ≠

  1. 블록 : 코드·프롬프트
  2. 시작 : 아키텍트 — 쪽지 : 넘길 것: 레포 · 시스템 프롬프트
  3. 건너뜀 : 인계 문서
  4. 넘김 : 코드·프롬프트 → 새 팀 : 코드에는 "무엇"만 있고 "왜"는 없다 ≠ — 말 : “context rot 이니 RAG 로 다시 비교하죠.”
  5. 끝 : 새 팀이 처음부터 다시 비교한다

③ 전제가 바뀐다 ✓

  1. 시작 : 아키텍트 — 쪽지 : ADR-007 / full context + 캐싱 / 전제: 계약 1건씩 검토
  2. 확인 : 인계 문서 : 그때와 무엇이 달라졌나? — 쪽지 : 그때: 1건 ≈ 3만 토큰 / 지금: 800건 전체 검색 / ≈ 2,400만 토큰
  3. 대체 : 인계 문서 → 새 팀 : 새 ADR 로 대체한다 — 쪽지 : ADR-012 RAG / ADR-007 = 대체됨
  4. 끝 : 옛 것은 지우지 않고 대체됨으로 표시한다

나머지 규칙

  1. 아키텍처 패키지 : ADR 묶음, 흐름 그림, 계획으로 이루어진다 (구성은 업계 일반) [6.4①]

    입력, 처리, 출력, feedback loop 의 흐름은 ■ input → processing → output → feedback loop 에 있다

    고른 패턴과 이유를 적는다. 자세한 것은 ◆ 워크플로 vs 에이전트 에 있다. 패턴은 가이드 기준 3개 workflow · agentic · augmented LLM 이다 (가이드 1.3)

    모델 선택과 평가 근거, 가드레일·규정 설계, 평가·모니터링 계획도 넣는다 업계 일반 목록 6.4①

    ADR 은 패키지 전체가 아니다. ADR 은 결정 기록이다. 다이어그램·구현 가이드·런북은 패키지의 다른 문서다 업계 일반. 자세한 것은 ■ 구현 가이드 에 있다

규칙 원문 ①②④⑤ (갈림길로 그린 규칙)

  1. ADR 한 장 : 결정, 맥락(문제·제약·위험·증거), 기각된 대안과 이유를 적는다 업계 일반 [6.4①]

    무엇을 적나 : 코드에서 못 읽는 것을 적는다. CLAUDE.md 에 넣을 것은 "프로젝트 고유의 구조 결정 · 흔한 함정" 이다. 뺄 것은 "코드를 읽으면 알 수 있는 것" 이다

    /doctor 는 CLAUDE.md 에서 코드로 알 수 있는 구조 개요·디렉터리 배치를 자른다. 함정·이유(rationale)는 남긴다

    구조 그림은 코드가 말해 준다. 그러나 "왜" 는 기록만 말해 준다 (사람 문서로 넓힌 것은 추론이다)

    크기 : 줄마다 "지우면 실수가 나나?" 를 묻는다. 아니면 뺀다. 길면 중요한 규칙이 묻힌다 (Claude 가 읽는 문서 기준)

  2. 근거는 평가 증거로 : "좋아 보여서" 대신 성공 기준과 평가셋 숫자(품질·지연·비용)를 적는다 [6.4①] [6.4③]

    공식 문서는 성공 기준을 정하고 평가를 설계하는 것을 출발점으로 둔다. 평가가 있으면 숫자가 짐작을 대신한다. 자세한 것은 ■ 성공 기준 · ■ 검증 층 에 있다

    근거 문장 자체가 공식 기준과 맞는지 확인한다. 예 : "100쪽 계약은 context rot 때문에 RAG". 자세한 것은 ◆ RAG vs full context 에 있다 (크기 먼저)

  3. 다시 여는 때 : 기록은 "논쟁 금지" 가 아니다. "그때와 무엇이 달라졌나" 부터 묻게 한다. 전제(데이터 크기·모델·가격·요구)가 바뀌면 새 ADR 로 대체한다. 옛 것은 지우지 않고 대체됨으로 표시한다 업계 일반 [6.4①]

    새 모델이면 평가셋으로 다시 확인한다. 평가가 있는 팀은 새 모델을 며칠 만에 판단한다

    문서는 코드처럼 다룬다. 일이 틀어지면 검토하고 주기적으로 쳐낸다 (CLAUDE.md 원칙)

  4. 둘 곳 : 코드 옆 레포(버전 관리)에 둔다. 회의록·채팅은 흩어져 새 팀이 못 찾는다 업계 일반. 공식 문서는 CLAUDE.md 를 git 에 넣어 팀이 기여하게 하라고 한다. 그러면 시간이 갈수록 쓸모가 쌓인다 [6.4①]

더 깊이 : 판단 규칙 · 상황 변수 (설명)

판단 규칙

조건답등급근거
인계 뒤 새 팀이 정해진 결정을 처음부터 다시 비교한다빠진 것은 결정 기록(결정·맥락·기각 대안)이다업계 일반목록 6.4①. Anthropic 문서에 ADR 이 없다 (grep "decision record|ADR|design doc" official-docs·skilljar 0건)
무엇을 기록하나?코드로 못 읽는 것을 기록한다. 구조 결정·함정·이유다(Claude 문서 기준)best-practices "persistent context it can’t infer from code alone" · "Architectural decisions specific to your project" · memory "keeps pitfalls, rationale"
무엇을 빼나?코드를 읽으면 알 수 있는 것, 긴 설명·튜토리얼, 자주 바뀌는 정보를 뺀다(Claude 문서 기준)best-practices 표(Exclude 칸)
결정 근거를 무엇으로 적나?성공 기준과 평가셋 숫자로 적는다define-success · demystifying-evals "metrics replace guesswork"
패턴을 적는다workflow · agentic · augmented LLM 중 무엇인지와 이유를 적는다가이드 목표 1.3
어디 두나?코드 옆 레포(버전 관리)에 둔다(CLAUDE.md 기준)best-practices "Check CLAUDE.md into git so your team can contribute"
전제가 바뀌었다새 ADR 로 대체한다. 옛 것은 대체됨으로 표시한다업계 일반—
새 모델이 나왔다ADR 의 모델 근거를 평가셋으로 다시 확인한다demystifying-evals (평가가 있는 팀은 며칠 만에 업그레이드)

상황 변수

변수값답 쪽등급근거
결정의 성질되돌리기 비싸고 논쟁 여지가 있다 (검색 방식 · 모델 · 패턴)ADR 로 남긴다업계 일반—
결정의 성질코드에 그대로 드러난다 (파일 배치 · 함수 이름)남기지 않는다(Claude 문서 기준)best-practices · memory
기록 위치회의록 · 채팅흩어져 새 팀이 못 찾는다업계 일반목록 6.4① 오답
기록 위치레포맞다(CLAUDE.md 기준)best-practices
근거 모양평가셋 숫자맞다define-success
근거 모양일반론("context rot", "엔터프라이즈답게")공식 기준부터 대조한다rag-vs-full 카드 · contextual-retrieval
개인 작업 중 결정내 브랜치에서만 쓰는 구조 결정팀 공유 파일이 아니라 local 파일(Claude Code)에 둔다(Skilljar)Skilljar 486929
문서 길이결정마다 긴 설명을 쓴다짧게 쓴다. 길면 묻힌다(Claude 문서 기준)best-practices

연습 문제

아키텍트가 떠나며 계약 검토 Agent 를 새 팀에 넘긴다. "왜 RAG 대신 full context(문서 전체를 넣기) + 캐싱인가" 는 코드를 읽어도 안 나온다코드에 없음. 아키텍트는 "근거는 슬랙 스레드에 다 있다채팅에 있음"고 한다. 이 결정의 근거를 어디에 어떻게 남길까?

시험 대비

함정

  • "빠른 인계를 위해 코드·프롬프트만 넘기고 질문은 그때그때" 는 함정이다. 코드에는 "무엇"만 있고 "왜"·기각 대안은 없다. 그래서 새 팀이 처음부터 다시 비교한다 업계 일반. 가까운 공식 원칙은 "코드로는 못 읽는 맥락" 이다
  • "결정 근거는 회의록·채팅에 다 있다" 는 함정이다. 기록이 흩어져 새 팀이 못 찾는다 업계 일반
  • "ADR 하나에 다이어그램·구현 가이드·런북까지" 는 함정이다. ADR 은 결정 기록이다. 나머지는 패키지의 다른 문서다 업계 일반 목록 영상 설명 교정
  • "ADR 이 있으니 결정은 못 바꿈" 은 함정이다. 전제가 바뀌면 새 ADR 로 대체한다 업계 일반
  • "근거 = context rot 이니 RAG" 는 함정이다. 공식 기준과 어긋난 근거다. 크기를 먼저 본다. 자세한 것은 ◆ RAG vs full context 에 있다
  • "패턴은 workflow · agent 둘" 은 함정이다. 가이드 기준은 augmented LLM 을 포함해 3개다
  • "결정마다 긴 설명·튜토리얼까지" 는 함정이다. 긴 설명은 CLAUDE.md 에서 뺀다. 길면 중요한 규칙이 묻힌다 (Claude 가 읽는 문서 기준)

신호

"Document architectures and provide implementation guidance" (가이드 목표 6.4)

"Architectural decisions specific to your project"

"This gives Claude persistent context it can’t infer from code alone."

"keeps pitfalls, rationale, and conventions that differ from tool defaults"

"Check CLAUDE.md into git so your team can contribute. The file compounds in value over time."

"Building a successful LLM-based application starts with clearly defining your success criteria and then designing evaluations to measure performance against them."

"development accelerates as failures become test cases, test cases prevent regressions, and metrics replace guesswork."

ADR 은 보통 재논쟁을 막지만, 규모 같은 전제가 바뀌면 새 ADR 로 대체하고, 코드로 알 수 있는 결정은 적지 않으며, 새 모델은 같은 평가셋으로 다시 본다.
그림으로 보기 (AI 생성 · Codex · 누르면 크게) — 자세한 조건은 아래 '더 깊이'에 있어요
더 깊이 : 뒤집히는 때 · 오답 재료 (설명)

뒤집히는 때

1. 기록한 결정이 뒤집혀야 맞는 때 — 전제(규모)가 바뀜

  • 조건 : ADR 은 "계약 1건(약 3만 토큰)씩 검토하니 full context(문서 전체를 넣기) + 캐싱" 이다. 1년 뒤 요구가 "계약 800건 전체에서 같은 조항 찾기"로 바뀌었다.
  • 계산 : 800 × 3만 = 2,400만 토큰이다. 1M 창도 한참 넘는다. 창에 안 들어가면 RAG 를 쓰는 것이 공식 기준이다.
  • 판단 : "ADR 이 있으니 못 바꿈"이 아니다. 새 ADR 로 대체한다. 옛 ADR 은 지우지 않고 "대체됨"으로 표시한다. 왜 처음에는 full context 였는지도 남아야 다음 사람이 헷갈리지 않는다.
  • 등급 : 계산 (크기 기준 · 창 크기는 확인, 대체 절차는 업계 일반)
  • 근거 : contextual-retrieval · context-windows

2. 기록할 필요가 없는 때

  • 조건 : 코드만 보면 알 수 있는 결정이다(폴더 배치, 라이브러리 목록). 또는 쉽게 되돌리는 결정이다.
  • 판단 : 적으면 오히려 중요한 기록이 묻힌다. Claude 문서 원칙은 줄마다 "지우면 실수가 나나?" 를 묻는 것이다.
  • 등급 : (Claude 문서 기준이다. 사람 문서로 넓힌 것은 추론이다)
  • 근거 : best-practices · memory

3. 새 모델이 나왔는데 ADR 이 "Sonnet 으로 결정" 이라고 적혀 있을 때

  • 조건 : 모델 근거가 1년 전 평가셋 점수다.
  • 판단 : 기록은 결론을 굳히는 것이 아니다. "무엇이 달라졌나"를 묻게 한다. 평가셋이 있으면 같은 셋을 새 모델로 돌려 며칠 안에 판단한다.
  • 근거 : demystifying-evals

4. 사람 문서 vs Claude 가 읽는 문서

  • 조건 : 같은 결정 기록을 사람 팀과 Claude Code(CLAUDE.md) 둘 다 본다.
  • 판단 : CLAUDE.md 는 매 세션 전부 읽힌다. 그래서 짧아야 하고, 긴 설명은 링크로 뺀다. 사람용 ADR 은 더 길어도 된다. 공식은 사람용 ADR 길이를 말하지 않는다.
  • 등급 : 미해결 (사람 문서 기준 공식 문장이 없다)
  • 근거 : best-practices

오답 재료

오답왜 끌리나왜 틀리나등급근거
"빠른 인계를 위해 코드·프롬프트만 넘기고 질문은 그때그때 답한다"빠르고 코드가 정답 같다코드에는 "무엇"만 있고 "왜"·기각 대안은 없다. 아키텍트가 떠나면 답할 사람도 없다업계 일반 (가까운 원칙 확인)목록 6.4① · best-practices
"결정 근거는 회의록·채팅에 다 있다"기록은 어딘가 있다흩어져 새 팀이 못 찾는다. 버전 관리도 안 된다업계 일반목록 6.4①
"ADR 에 다이어그램·구현 가이드·런북을 다 담는다"ADR 을 문서 전부로 오해한다ADR 은 결정 기록이다. 나머지는 패키지의 다른 문서다업계 일반목록 6.4① 영상 설명 교정
"ADR 로 정했으니 결정은 바꿀 수 없다"재논쟁 방지를 변경 금지로 오해한다전제가 바뀌면 새 ADR 로 대체한다업계 일반뒤집히는 때 1
"ADR 근거 : 100쪽 계약은 context rot 때문에 RAG"context rot 은 공식도 인정한다20만 토큰 미만이면 full context + 캐싱이 공식 첫 선택이다◆ RAG vs full context · contextual-retrieval
"패턴은 workflow 와 agent 두 가지만 적는다"강의가 2개로 설명한다가이드 기준은 augmented LLM 을 포함해 3개다가이드 목표 1.3
"모든 결정·설명을 빠짐없이 길게"완전할수록 좋아 보인다길면 중요한 규칙이 묻힌다. 코드로 알 수 있는 것은 뺀다(Claude 문서 기준)best-practices
"모델 선택 근거 = 벤치마크 순위 · 가장 좋은 모델"객관적인 것 같다근거는 이 과제의 성공 기준·평가셋 숫자다define-success

참고

더 깊이 : 출처 · 상태 · 미해결 (참고)

출처

상태

  • 업계 일반 (ADR 양식 · 패키지 구성 · 대체 절차 — 공식 문서 없음)
  • 추론 1곳(CLAUDE.md 원칙 → 사람 문서)

미해결

  1. ADR 양식·아키텍처 패키지 구성은 Anthropic 공식 문서가 없다. grep "decision record|ADR|design doc" 결과는 ccarp/raw/official-docs · ccarp/raw/skilljar 에서 0건이다 (제외 = 받지 않은 공식 페이지). 그래서 카드는 목적 위주로 썼다. 구성은 목록 6.4① 을 업계 일반으로 옮겼다.
  2. 공식 원칙(CLAUDE.md "코드로 못 읽는 것만")은 Claude 가 읽는 문서 기준이다. 사람 팀 결정 기록에 옮긴 것은 추론이다 (뒤집히는 때 4).
  3. 목록 6.4① 의 영어 신호 두 개(가이드 목표 6.4 · "Architectural decisions specific to your project")는 원문에서 찾았다. 목록과 공식이 어긋난 곳은 없다.
  4. Skilljar Claude Code in Action 486929 는 CLAUDE.md local 파일에 "개인 브랜치의 구조 결정"을 두라고 한다. 팀 공유 결정은 프로젝트 파일에 둔다. 시험이 이 구분을 묻는지는 모른다.