research

ADR as Strategic Mechanism — 학생의 진짜 자산

ADR as Strategic Mechanism — 학생의 진짜 자산

AI가 코드·design·결정을 다 도와주는 시대에 *"내가 무엇을 아는가?"*의 답. ADR (Architecture Decision Record)이 strategic 사고를 글로 남기는 가장 명확한 mechanism. 14 원칙 + Matt thesis가 모두 가리키는 학생 단위 운영 도구.

한 줄

ADR = 매 큰 결정마다 옵션·선택 이유·가정을 글로 남기기. AI가 코드·옵션·심지어 결정도 제시하지만, "내 도메인에 왜 이 선택인가"의 판단은 사용자의 영역. ADR이 그 판단을 명료한 형태로 남기는 도구. 5장 쌓이면 자기 판단 패턴이 보이고, 10장이면 자기 도메인의 strategic architect가 됨.

⚛️ 왜 ADR인가

AI 시대 학생의 핵심 고민

"내가 직접 코딩하지 않고 LLM에게 다 물어봐서 결정한다. 그러면 내가 뭘 아는 거지?"

이 고민의 정확한 답은 결정의 결과가 아니라 결정의 과정에서의 판단력. LLM이 옵션을 제시해도 왜 이 옵션이 맞는가는 사용자 몫.

❌ "LLM이 이렇게 하라고 해서 했음"
   → no judgment, no learning, no asset

✅ "LLM이 3가지 옵션 줬고, 내 도메인에 *왜* 이게 맞는지 판단하고 선택"
   → judgment + ADR로 표현 + 자산

ADR이 답하는 질문

매 ADR이 4가지 질문에 답:

  1. 무엇을 결정했는가? (선택)
  2. 어떤 옵션이 있었는가? (alternatives)
  3. 왜 이 선택인가? (rationale)
  4. 이 선택의 가정은 무엇인가? 가정이 깨지면? (assumptions + reversibility)

→ 이 4가지가 학생이 진짜 아는 것의 정의.

📝 ADR Template

# ADR-{번호}: {결정 제목 한 줄}

## Date
{YYYY-MM-DD}

## Status
{Proposed | Accepted | Superseded by ADR-XXX}

## Context (상황)
- 무엇을 결정해야 하나
- 왜 지금 결정해야 하나
- 도메인 제약 (시간, 리소스, 사용자, 기술)

## Options (옵션)
1. {옵션 A} — 장단점
2. {옵션 B} — 장단점
3. {옵션 C} — 장단점
   (LLM이 제시한 옵션도 OK, 내가 검증한 옵션 모음)

## Decision (결정)
{어떤 옵션 선택}

## Rationale (왜)
- {도메인 제약과의 fit}
- {시간 제약}
- {사용자 제약}
- {trade-off 인지}

## Assumptions (가정)
- {이 결정이 옳기 위해 참이어야 할 가정 1}
- {가정 2}

## Reversibility (가정이 깨지면?)
- {가정이 깨지는 신호}
- {그때 어떻게 되돌리는가}
- {compensating action}

## References
- 관련 ADR
- 관련 [[14 원칙 노트]]
- 외부 source

→ 이 template 채우는 데 30분~1시간. 1주일 설계가 아닌 작은 단위 strategic 사고.

🌱 ADR 5장 쌓이는 path

ADR-001: Strategic Kickoff (Day 0)

# ADR-001: 학내 도구 만들기 - strategic kickoff

## Context
"수강신청 시간표 충돌 검사기"를 만들고 싶음
- 내 시간: 주 5시간
- 사용자: 나 + 동기 1-2명
- 도메인: 한국 학내 학사 시스템

## Options
1. Spring Boot 백엔드 + 웹 (큰 시스템, 친숙)
2. Python script (작고 빠름)
3. Rust CLI (학습 + 효율)

## Decision
2번 — Python script

## Rationale
- 사용자 1-2명 → 큰 시스템 over-engineering
- Tracer bullet으로 빠르게 작동 확인 우선
- 친숙해서 AI에게 시키기 쉬움

## Assumptions
- 사용자 늘면 1년 후
- 학사 시스템 API 접근 가능

## Reversibility
- 사용자 5명+ 되면 → 백엔드로 마이그레이션
- API 안 되면 → web scraping 또는 폐기

ADR-002: 학사 시스템 통합 방식 (Week 2)

# ADR-002: 학사 시스템 통합 - 직접 호출 vs ACL

## Context
- 학사 시스템 API가 학기마다 바뀜 (들음)
- 도구가 5개로 늘어날 가능성

## Options
1. 직접 호출 (간단)
2. ACL layer (격리)
3. 외부 lib 사용 (학습 부담)

## Decision
2번 — ACL layer

## Rationale
- 학기마다 바뀜 *3번 이상* 예상 → 격리 가치 큼
- 시간 제약상 lib 학습보다 직접 ACL이 빠름
- 학내 도메인 vocabulary가 외부 lib에 잘 안 맞음

## Assumptions
- 학사 시스템 1학기 1-2회 변경
- 도구 5개+로 늘어남

## Reversibility
- 도구 1-2개로 끝나면 → ACL은 over-engineering, 폐기
- 변경 빈도 낮으면 → 직접 호출로 후퇴

## References
- [[anti-corruption-layer]] — ACL 원칙

ADR-003: AI agent vocabulary skill (Week 3)

# ADR-003: 학내 vocabulary skill 만들기

## Context
- AI에게 "수강신청 검증해줘" → AI가 "course registration form submission validation logic"으로 verbose 응답
- token 비용·정확도 모두 떨어짐

## Options
1. 매 prompt에 한국어 단어 풀어쓰기
2. SKILL.md frontmatter에 vocabulary
3. AGENTS.md에 vocabulary 박기

## Decision
2번 + 3번 — SKILL.md vocabulary + AGENTS.md glossary

## Rationale
- vocabulary가 *모든 skill에 공통* → AGENTS.md
- skill별 specific vocabulary → SKILL.md
- 한국어 학사 용어가 *고유 정밀도* 있어 그대로 사용

## Assumptions
- AI가 한국어 vocabulary를 *그대로* 사용 가능
- 다른 도메인(연구·동아리)은 별 vocabulary

## References
- [[ubiquitous-language]] — UL 원칙
- [[bounded-context]] — 도메인 분리

ADR-004: Test 작성 vs 수동 검증 (Sprint 2)

# ADR-004: AI agent에게 test를 보호하게 강제

## Context
- AI가 test fail 시 *test를 변경*하는 함정 발견
- 결과: code는 fail인데 test는 통과 (false success)

## Options
1. Test 없이 수동 검증
2. Test 있고 AI에게 *수정 가능*
3. Test 있고 AI에게 *수정 금지* (Anthropic 패턴)

## Decision
3번 — Anthropic prompt 패턴 차용

## Rationale
- false success가 가장 위험
- *수정 금지* prompt가 명료하고 enforce 쉬움
- 12% production cohort의 패턴

## Assumptions
- Test가 *내가 의도한* 행동을 정확히 표현
- AI가 prompt 따름 (Anthropic 모델 가정)

## Reversibility
- Test 자체가 잘못된 것 발견 → 사람이 직접 test 수정 (AI X)

## References
- [[tdd-as-small-deliberate-steps]]
- [[sources/key-articles-summary#3. Anthropic - *Effective Harnesses*]]

ADR-005: 후배에게 인계 준비 (Week 12)

# ADR-005: 졸업 전 owner transfer 준비

## Context
- 1학기 사용 후 후배에게 도구 인계 예정
- 후배가 fundamentals 모름

## Options
1. 코드 + git만 인계 (최소)
2. README + 인계 문서 (중간)
3. AGENTS.md + ADR 묶음 + 1시간 onboarding (충실)

## Decision
3번

## Rationale
- 후배가 *왜 이런 결정인지* 알아야 변경 가능
- ADR이 *판단 패턴* 학습 자료
- 1시간 onboarding이 *암묵 지식* 전달

## Assumptions
- 후배가 1주일 사용해보고 onboarding session
- 후배가 ADR 형식 학습 가능

## References
- [[named-ownership]] — owner transfer
- [[information-leak-vs-abstraction]] — 인계 문서 = leak 측정

→ 5장 쌓이면 자기 판단 패턴이 보임:

  • ADR-001 (큰 시스템 over-engineering 회피)
  • ADR-002 (외부 변화 격리)
  • ADR-003 (vocabulary 정착)
  • ADR-004 (AI agent 안전)
  • ADR-005 (owner transfer)

→ 모두 내 도메인의 strategic 결정. 후배가 ADR 5장 읽으면 나의 사고방식을 흡수.

🔗 ADR과 14 원칙의 연결

ADR이 14 원칙의 학생 단위 운영 mechanism:

14 원칙ADR이 보장하는 부분
strategic-vs-tactical-programmingADR 자체가 strategic 시간의 결정체
reversibilityADR의 Assumptions + Reversibility 섹션
named-ownershipADR 작성자가 결정의 owner
information-hidingADR이 왜 secret인지 설명
anti-corruption-layerADR이 언제 ACL이 필요한지 판단
bounded-contextADR이 왜 BC를 여기서 끊는지 명시
tracer-bulletsADR-001이 tracer bullet 발사 전 design

→ ADR이 14 원칙의 추상 명제를 구체 결정으로 변환하는 도구.

🤖 AI 시대 specific — AI에게 ADR 작성을 위임할 수 있는가?

흥미로운 질문. 답은 부분적 yes, 그러나 핵심은 사람:

ADR 부분AI 위임 OK?
Context (상황)✅ AI가 형식 정리 도와줌
Options (옵션 제시)✅ AI가 옵션 brainstorm. 그러나 내가 검증
Decision (선택)❌ 사람의 영역. judgment 필요
Rationale (왜)❌ 사람의 영역. 도메인 + 제약 + 시간 보고
Assumptions (가정)❌ 사람의 영역. 가정은 내 도메인 지식에서
Reversibility (되돌림)⚠️ AI가 기술적 가능성은 보지만 사회적·시간적 비용은 사람

→ Decision · Rationale · Assumptions가 학생의 진짜 자산이 형성되는 자리. 이 셋만 사람이 쓰면 됨. 나머지는 AI 위임 OK.

학생의 진짜 자산 = "Why·What if 질문에 답하는 능력". ADR이 그 능력의 증거.

⚙️ 실용 운영 — ADR을 어디에 어떻게 쓰는가

저장 위치

학생 프로젝트 권장 구조:

project-root/
├─ docs/
│   └─ adr/
│       ├─ ADR-001-strategic-kickoff.md
│       ├─ ADR-002-haksa-integration.md
│       ├─ ADR-003-vocabulary-skill.md
│       ├─ ADR-004-test-protection.md
│       └─ ADR-005-transfer-prep.md
├─ src/
└─ README.md

Git 통합

  • 매 ADR이 separate commit. 왜 이 결정인지 commit history에 남음
  • ADR이 변경되면 Status: Superseded by ADR-XXX로 link

빈도 가이드

  • 반드시 ADR: 큰 architectural 결정 (vendor, 외부 시스템, BC 분리, deprecation)
  • 권장 ADR: 중간 결정 (라이브러리 선택, design pattern)
  • 불필요: 작은 구현 디테일 (변수 이름, 함수 시그니처)

→ ADR이 너무 많으면 의미 없음. 1 sprint에 1-3장이 적정.

시간 가이드

  • ADR-001 (kickoff) — 30분 ~ 1시간
  • 기능 ADR — 30분
  • 큰 architectural ADR — 1-2시간
  • 절대 1주일 설계 = ADR 1장은 잘못된 단위

🧘 학생 마음 무게 — ADR이 자산을 가시화

학생의 불안:

"AI 시대에 내가 뭘 아는지 모르겠다."

해법 — ADR을 쓰면 지식이 가시화되어 불안이 자산으로 변환:

ADR 0장:
  "내가 뭘 아는지 모름" → 불안

ADR 1-3장:
  "이 결정들은 내가 했음" → 작은 자신

ADR 5장:
  자기 판단 *패턴*이 보임 → "내 사고방식"

ADR 10장:
  자기 도메인의 strategic architect → 자산 명확

5번째 ADR쯤이면 자기 판단 패턴이 글로 보임. 10번째쯤이면 후배에게 가르칠 수 있는 수준. 이게 named-ownership 인사이트 8 — *"AI 사용 자유와 결과 책임 의무는 분리되지 않는다"*의 학생 단위 mechanism.

한 줄 답

학생이 진짜 아는 것 = ADR 묶음 그 자체. AI 시대에 코드 문법이 아니라 ADR로 표현되는 판단력이 자산.

관련

Sources

ADR 일반 source

Strategic decision making

  • The Pragmatic Programmer — Hunt & Thomas. Tip 14 (Reversibility) + ADR 정신
  • A Philosophy of Software Design — Ousterhout. Strategic vs Tactical (ADR이 strategic의 결정체)

AI 시대 ADR

← research 목록으로홈으로