[Third tool] AI 시대의 Doc-Driven Workflow: Living Docs로 하네스 잡기, 그리고 사람의 영역

junsung kim·2026년 5월 8일

AI DDD LivingDocs claudecode thirdtool workflow 백엔드

[project]- thirdTool

목록 보기

30/33

AI에게 문서를 맡길 때 무너지는 건 정확성이 아니라 소유권(ownership) 과 결정의 날카로움이다.

들어가며 — 두 번 다른 길을 걸어봤다

Doc-driven workflow를 ThirdTool에 적용하면서, 같은 도메인 모델링 문서를 두 가지 방식으로 작성해봤다.

[방식 A] Top-down
  목차/프롬프트 먼저 → 검토 후 빈칸 채워가며 문서화
  → epic/story 그 위에서 진행

[방식 B] Living
  최소한의 모델링 doc(속성/행동/규칙)만 두고 시작
  → epic 진행하며 학습된 것이 문서로 흘러들어옴
  → 살아서 리팩토링되는 문서

처음엔 "어느 쪽이 더 나은가" 식으로 답을 찾으려 했는데, 한참 굴려보고 나서 그게 잘못된 질문이었다는 걸 알았다. 두 방식은 다른 trade-off curve를 가지고 있고, 어느 쪽이 우월한 게 아니라 상황별로 적합한 영역이 다르다.

다만 내 작업 성격(도메인 모델링 + 학습 + 1인 진화 서비스 + Claude Code 하네스 운영)에서는 B쪽이 더 잘 맞았다. 그 이유와 한계를 정리하면서, 결국 두 방식을 어떻게 layered로 섞어 쓰는지까지 가본다.

1. 두 방식의 Trade-off 매트릭스

Top-down 방식

〔장점〕
- 구조적 완결성       → 누락을 구조적으로 잡아줌
- 큰 그림 가시성       → 전체 지도를 한눈에
- 표준화 / 공유 용이   → 팀에서 같은 형식 강제 가능
- 신참 onboarding     → 입사자가 한 번에 따라잡기 좋음
- 안 변하는 영역에 강함 → 외부 계약, 컴플라이언스, 감사 대비

〔단점〕
- 정답 모를 때 정답 구조부터 만드는 모순 - 이 모순이 컸다.
- 빈칸 강제 → AI가 균형 맞추려 hallucination
- sunk cost → 잘못 잡힌 목차가 작업을 끌고 감
- 의도 정렬 < 형식 충실도 → 칸 채우기 게임이 됨
- 학습 반영 어려움 → "완성품"으로 인식되어 수정 진입 장벽

Living 방식

〔장점〕
- 진짜 필요한 것만 자람 → lean
- 학습 동기화           → 이해 ≈ 문서 상태
- 진입 비용 낮음        → 첫 작업까지 빠름
- AI에 좋은 컨텍스트     → 항상 "현재 진실"만 제공
- 도메인 모델링/탐색에 본질적으로 정합
- 하네스 운영 친화적     → (다음 섹션에서 자세히)

〔단점〕
- 큰 그림 누락 위험     → 중복/사각지대 (확실히 피드백이 많이 필요할 것 같음) 
- 정합성 침식           → 시간 지나면 문서 간 충돌
- 결정 history 흐릿     → "왜 이렇게 됐지?" 추적 어려움
- onboarding 약함       → 새 사람은 "현재"만 보고 "맥락" 못 봄
- 후반부 refactoring 비용 누적

만족도가 갈렸던 건 절대적 우위가 아니라, 내 작업 컨텍스트에서 living의 장점이 더 크게 작동하고 단점은 덜 아팠기 때문이었다.

2. 내 컨텍스트에서 Living이 잘 맞았던 이유

세 가지가 동시에 정렬됐다.

[도메인 모델링의 본질]
  - 발견적(emergent) 작업
  - 속성/행동/규칙은 코드를 짜며 드러남
  - "이 필드 있어야 하나?" 는 use case 만나야 답이 나옴
  → 미리 채울 수 있는 정보가 적음
  → top-down은 빈칸을 강제로 채우게 됨

[학습 곡선과의 정합]
  - 사람의 이해는 점진적으로 깊어짐
  - top-down 문서는 내 이해 수준과 mismatch
    (이해 안 된 채로 문서에 적힌 항목들이 떠다님)
  - living은 이해 곡선과 동기화됨

[AI의 약점 회피]
  - top-down에서 빈칸이 많으면 → AI가 균형 맞추려고 hallucination
  - "Card는 7개 속성이 자연스러워 보이니 채우자" 식의 합성
  - living은 "이번에 진짜 필요한 것"만 다루므로 합성 여지가 적음

ThirdTool에서 AxisAction → AxisTopic으로 마이그레이션할 때가 좋은 예다. 처음에 AxisAction이라고 명명한 이유는 "사용자 학습 행동 단위"라는 직관에서 출발했는데, ReviewLog의 user action과 의미 충돌이 나면서 학습 흐름을 표현하기에 부적절해진 거다.

이걸 top-down 문서에 미리 넣을 수 있었을까? 못한다. 돌아갔기 때문에 알게 된 거다. Living docs는 이런 학습을 받아낼 수 있었고, top-down docs였다면 잘못된 사전 합리화를 박제했을 거다.

3. Living이 하네스 운영에 좋았던 추가 이유

이건 따로 빼서 쓸 만한 가치가 있다. 단순히 "도메인 모델링에 좋다"를 넘어, Claude Code 하네스 운영 관점에서 구조적 우위가 있었다.

3-1. 모듈성 — 발췌가 자연스럽다

[top-down]
  - 한 덩어리 종합 문서
  - 매 story마다 "이 부분만 떼어서" 가 부자연스러움
  - 결국 통째로 넘기거나, 발췌하는 데 별도 노력 필요

[living]
  - 작은 단위 doc이 분산되어 있음
  - story-local harness에 그대로 발췌 가능
  - "이번 작업에 관련된 living doc 3개" 같은 단위가 자연스러움

작업 단위와 문서 단위가 일치하니까 발췌 비용이 거의 없다.

3-2. 컨텍스트 가벼움 — Claude Code에 던지기 좋다

Claude Code 세션에 컨텍스트를 넘길 때 분량과 정확도가 직접 품질에 영향을 미친다.

- 큰 종합 문서 통째로 넘기면 → 무관한 정보가 노이즈
- AI가 노이즈에서 잘못된 패턴을 짚어낼 위험
- token도 비싸짐

→ living은 작업과 관련된 좁은 범위만 넘길 수 있어 hit rate↑

특히 200줄 제한 둔 CLAUDE.md/rules와 결합하면, "규칙은 늘 로드, 디테일은 on-demand" 의 분리가 자연스럽게 나온다.

3-3. 속도 동기화 — story와 docs의 진화 속도가 같다

[top-down]
  - docs는 사전에 freeze, story는 작업하며 진화
  - 시간 지날수록 docs ↔ 코드 갭 누적
  - 갭 인식 → 큰 docs 수정 마찰 → 갭 방치

[living]
  - story 진행 = doc 갱신
  - 갭이 누적되지 않음
  - 오히려 docs가 작업의 by-product로 자연 생산

진행 중인 story의 학습이 즉시 다음 story의 컨텍스트가 된다.

3-4. 수정 비용 낮음 — 작업 중 발견한 모순을 즉시 반영

[top-down]
  - "이미 잘 만들어진 doc"을 수정하는 심리적 마찰
  - 다른 부분과의 정합성 다시 점검 부담
  - 결과: 모순을 발견해도 사이드 메모로 남기고 미룸

[living]
  - 원래 진화하는 문서로 설계됨
  - 수정에 대한 마찰이 낮음
  - 모순이 발견되는 즉시 반영 → 정합성 유지 비용↓

3-5. 실험 친화적 — 새 패턴 시도가 쉽다

- 새 라이브러리, 새 패턴 도입할 때
- top-down은 "큰 그림 미리 그리기" 가 시작 장벽
- living은 작은 doc 1개로 실험 시작
- 안정화되면 승격 (Layer 1 ADR로)
- 실패하면 그냥 폐기

유사한 멘탈모델

이 사이클은 배포 전략으로 치면 **canary 배포**와 구조가 똑같다. 새 버전을 작은 트래픽 비율로 먼저 흘리고, 메트릭 보면서 문제 없으면 점진적으로 비중 늘리고, 안정화되면 100%로 전환하는 흐름. Living docs의 실험 → 승격 사이클도 같은 모양이다.

[Canary 배포]
새 버전 5% → 25% → 50% → 100% 트래픽

[Living docs canary]
작은 living doc → 한 BC에서 검증 → 2~3 BC로 확대 → ADR + CLAUDE.md 규칙으로 강제 (해당 프로젝트에 대한 트레이드오프를 새로운 testing에 대해 고민해볼 수 있다.)


핵심은 **점진적 확대 + 안정화 후 표준화**다. 단계별로 풀면:

〔1. Canary〕 작은 living doc으로 한 BC에 시범 적용
〔2. Observe〕 다음 story에서도 자연스럽게 들어맞는지 관찰
〔3. Expand〕 2~3 BC에서 일관되게 안정화
〔4. Promote〕 ADR로 결정 기록 + CLAUDE.md 규칙으로 강제


ThirdTool에서 새 패턴(분산락, Outbox, soft delete cascade 같은 것)을 도입할 때 이 사이클이 잘 먹혔다. 안정화 못 된 패턴은 living doc 단계에서 그냥 폐기되니까 롤백 비용도 작다. 반대로 처음부터 ADR/규칙으로 박아놓고 시작했으면, 실패가 드러났을 때 이미 코드베이스 곳곳에 퍼져 있어서 떼어내는 비용이 컸을 거다.

> 즉, **Layer 2 living doc은 Layer 1으로 가기 위한 canary 단계**다. 한 번에 규칙으로 승격시키지 말고, "이 패턴을 모든 BC에 강제해도 되겠다" 는 확신이 누적되면 그때 promote.

ThirdTool에서 Redisson 분산락을 처음 도입할 때 이 패턴이 잘 먹혔다. 작은 living doc으로 실험 → 안정화된 패턴은 ADR과 CLAUDE.md 규칙으로 승격.

3-6. AI 합성 노이즈 감소 — 빈칸이 적다

- top-down은 구조적으로 빈칸이 많음 (목차에 비해 내용 부족)
- AI는 빈칸을 견디지 못하고 "그럴듯한" 내용으로 채움
- 이번 작업에 무관한 합성 결과가 다음 작업의 컨텍스트로 흘러감
- 가장 크게 느낀 건 어느 순간 내가 원하는 테스팅의 방향성으로 가지 않고 점점 기성품에 가까운 소프트웨어가 되가는 느낌이였다. 

- living은 "이번에 필요한 것"만 다룸
- 빈칸 자체가 없거나 명시적 ⚠️ TBD로 표시
- AI 합성 여지가 줄어듦

이 효과는 누적된다. 한 번 잘못 합성된 내용이 다음 doc 생성의 입력이 되면 오류가 증폭된다. Living은 이 누적 경로 자체를 짧게 유지한다.

4. 그럼에도 — Living만으로는 무너지는 지점

위 장점들이 매력적이라 한 번은 미끄러질 뻔했다. "Living이 좋으니 모든 docs를 living으로 운영하자" 는 결론으로 가려고 했는데, scale이 올라가면 다른 힘이 작동한다.

〔P0: 정합성 침식〕
  - living docs N개가 시간 따라 미세하게 어긋남
  - 같은 사실이 doc A에선 X, doc B에선 X' 로 적혀있음
  - Claude Code가 다른 doc 보고 다른 답을 냄
  → N이 커질수록 비선형으로 커짐

〔P0: 결정 history 손실〕
  - "왜 AxisAction → AxisTopic 이었지?" 추적 불가
  - living은 "현재"만 보여주고 "왜"는 못 보여줌
  - 인터뷰에서 의사결정 이유 못 답하면 치명적

〔P1: 외부 계약 깨짐〕
  - API 스펙이 living이면 클라이언트 입장에서 신뢰 못함
  - 결제/Toss 같은 외부 통합은 freeze가 본질
  - "어제는 됐는데 오늘은 안 되네"

〔P1: 잘못된 합성의 누적 경로〕
  - 모호한 표현이 끼어들면 Claude Code가 "합리적으로 해석"
  - 합성된 코드가 다음 living doc에 반영되며 누적
  - 위 3-6 장점의 정확히 반대편 위험

위 trade-off 매트릭스의 단점들이 실제로 모습을 드러내는 지점이다. 즉 하네스 운영의 강점은 작은~중간 scale에서 가장 크고, 큰 scale에선 정합성 비용이 따라온다.

5. 해법 — Layered Living Docs (3-Layer)

그래서 도착한 답은 하네스를 단일 계층으로 보지 말고 3-Layer로 분리하는 거다. 각 layer가 다른 lifecycle을 가진다.

[Layer 1: Frozen Core]  〔P0: top-down, freeze 후 ADR로만 변경〕
  - 도메인 용어집 (Ubiquitous Language)
  - ADR 모음 → 결정 + 이유 + alternatives
  - 외부 API 계약 (OpenAPI 스펙)
  - DB 마이그레이션 history
  → 변경 시 별도 PR + 이유 기록 강제

[Layer 2: Living Working Set]  〔P1: 만족도 높았던 방식 그대로〕
  - 도메인 모델링 doc (속성/행동/규칙)
  - 진행 중 학습 노트
  - 테스트 모델링 doc
  - 작업 중 발견된 제약사항
  → story 진행하며 자유롭게 수정

[Layer 3: Story-local Harness]  〔P2: 일회성〕
  - 이번 story의 작업 지시서
  - 이번 story에 관련된 Layer 1, 2 발췌/링크
  - 완료 후 폐기 또는 git history로만 보존
  → Claude Code 세션 컨텍스트

매 story마다 Layer 3를 새로 짜고, 그 안에서 Layer 1은 참조만, Layer 2는 갱신 가능, 이런 식이다. Living의 하네스 운영 강점은 Layer 2~3에서 그대로 살리고, 정합성 침식은 Layer 1으로 가둔다.

Living → Frozen 승격 패턴

진화하던 사실이 안정화되는 순간이 있다. 이때 Layer 2 → Layer 1으로 승격시키면 정합성이 유지된다.

- 같은 도메인 규칙이 3 story 연속 안 바뀜  → 용어집으로 승격
- 의사결정이 두 번 이상 흔들리지 않음      → ADR 작성
- API가 외부에 노출됨                      → 스펙 freeze
- 테스트 패턴이 정착됨                     → 컨벤션 문서로

ThirdTool에 적용하면:

AxisAction → AxisTopic 같은 마이그레이션 결정 → ADR (Layer 1)
LearningFacade의 메서드 시그니처가 진화 중이면 → Layer 2
Card AR의 embedded VO 구조가 안정화됐으면 → Layer 1

6. 사람이 쥐고 있어야 할 5가지 판단 축

Layer 구조를 만든다고 끝이 아니다. 각 layer의 어디까지 AI에게 맡기고, 어디부터 사람이 쥘 것인가가 다음 문제다.

문서를 AI에게 맡길 때 무너지는 건 정확성이 아니라 소유권과 결정의 날카로움이다. AI는 그럴듯한 문장을 너무 잘 써서, 어딘가 합리적으로 보이는 문서가 자동으로 만들어진다. 다시 읽었을 때 진짜 내 결정인지 사후 합리화인지 구분이 사라진다.

문서 항목 단위로 다음 다섯 질문을 던진다. 하나라도 사람 쪽이면 사람이 쥔다.

〔A1〕 Reversibility    바꾸려면 비용이 큰가?           (irreversible → 사람)
〔A2〕 Ownership        내 색깔/취향/철학이 드러나는가?  (yes → 사람)
〔A3〕 Truth grounding  AI가 거짓말해도 알아챌 수 있나?  (no → 사람 검증 필수)
〔A4〕 Context depth    팀/프로젝트 맥락이 깊이 필요한가? (deep → 사람)
〔A5〕 Why vs What      의도(Why)인가 형태(What)인가?    (Why → 사람)

이 5축을 기준으로 문서 종류별 매트릭스를 정리해본다.

7. 문서 종류별 분리 매트릭스

7-1. Domain Modeling 문서

〔사람〕
- BC 경계 결정              → 한번 그으면 코드 구조 전체가 따라옴 (A1, A2)
- Aggregate Root 선택       → "어떤 트랜잭션 일관성을 지킬 것인가" 결정 (A1, A5)
- VO/Entity 분류 기준       → 식별성 vs 값 동등성 모델링 철학 (A2)
- Ubiquitous Language 핵심어 → "AxisTopic이라 부른다"는 결정은 도메인 정체성 (A2, A4)
- Invariant 정의            → 깨지면 안 되는 규칙은 비즈니스 본질 (A5)

〔AI〕
- 필드 후보 나열, 타입 시그니처 초안
- 메서드 시그니처 일관성 점검
- 기존 BC 형식에 맞춰 신규 BC 골격 생성
- ASCII 다이어그램
- equals/hashCode 등 보일러플레이트 명세

핵심: AI는 "AxisAction이 더 동작 중심이고 AxisTopic이 더 주제 중심"이라는 식의 사후 합리화는 무한히 잘 만든다. 진짜 이유 — "Action이라는 단어가 ReviewLog의 user action과 의미 충돌해서 학습 흐름을 표현하기에 부적절했다" — 같은 본인 문맥은 모르고, 모르는 채로 그럴듯한 다른 이유를 채워 넣는다. 이걸 그대로 두면 6개월 뒤에 본인도 흔들린다.

7-2. ADR (Architecture Decision Record)

ADR은 형식이 "Context / Decision / Consequences / Alternatives"라 AI에게 통째로 맡기기 가장 위험한 문서다.

〔사람〕
〔P0〕 Decision 한 줄         → ADR의 본체. 양도 불가 (A1, A2, A5)
〔P0〕 진짜 Why               → "왜 이걸 골랐는가"의 실제 동기 (A2, A5)
〔P0〕 Trade-off 인정 부분    → 무엇을 포기했는지 의식적으로 (A2)
〔P1〕 Consequences 중 위험   → 운영 가서 무너질 가능성에 대한 직감 (A4)

〔AI〕
〔P1〕 Context 사실 정리       → "현재 시스템은 X 상황이다"
〔P1〕 Alternatives 후보 나열  → "고려 가능한 옵션은 A/B/C/D"
〔P1〕 각 Alternative의 일반적 장단점
〔P2〕 ADR 형식 통일, 번호 부여, 인덱스 갱신

가장 위험한 failure mode — AI에게 "이 결정에 대한 ADR 써줘"라고 하면 결정에 맞춰 Why를 만들어낸다. 진짜 Why는 "그날 X 라이브러리 문서 보다가 이게 맞겠다 싶어서"일 수 있는데, AI는 그걸 "확장성, 유지보수성, 팀 학습 곡선을 종합 고려하여…" 같은 결정 후 정당화로 포장한다. 면접에서 ADR 기반 깊은 질문에 본인이 무너지는 이유가 여기 있다.

→ 권장 운영: ADR은 사람이 손글씨처럼 Decision + Why 한 단락 먼저, AI는 그 뒤에 Context/Alternatives만 살을 붙임. 순서 중요.

7-3. API Spec

〔사람〕
- 엔드포인트 URL 디자인         → 리소스 모델링 자체가 도메인 결정 (A1, A2)
- 에러 코드 체계 / 도메인 prefix → 시스템 전체에 영향 (A1, A4)
- Validation 규칙의 비즈니스 의미 → "왜 이 필드가 필수인지" (A5)
- 멱등성/락/동시성 정책          → 결제·재시도 영역 (A1, A4)
- Public API의 호환성 약속       → 한번 내보내면 회수 어려움 (A1)

〔AI〕
- Request/Response 스키마 초안
- Example payload (정상/에러)
- OpenAPI / Swagger 변환
- DTO 클래스 코드 생성
- HTTP status code 매핑 일관성 체크

ThirdTool 예시 — Card 생성 API에서 "MainNote, Summary는 embedded VO이고 KeywordCue는 child entity"라는 결정은 사람의 도메인 모델링 결과물이다. 이걸 AI한테 그냥 "Card 생성 API 명세 짜줘" 하면, AI는 자기가 자주 본 패턴대로 KeywordCue를 단순 String 배열로 평탄화하기 쉽다. 그러면 복습 로직과의 정합성이 무너진다.

7-4. Test Modeling 문서

〔사람〕
- 테스트해야 할 핵심 invariant 식별 → "이게 깨지면 도메인이 망한다" (A4, A5)
- Edge case 우선순위               → 어떤 깨짐이 가장 비싼지 (A2, A4)
- Slice vs Unit vs E2E 분리 정책   → 아키텍처 이해 기반 (A2, A4)
- Mock 경계 결정                   → port-adapter에서 어디를 자르는지 (A2)
- 의도적으로 안 쓸 테스트 결정      → "비용 대비 가치 낮아서 뺀다" (A2)

〔AI〕
- 시나리오 매트릭스 (입력 조합)
- Given-When-Then 풀어내기
- 테스트 데이터 픽스처
- 동등 클래스/경계값 분석
- 테스트 코드 스켈레톤
- 누락 케이스 cross-check (사람이 지정한 invariant 기준)

LearningFacade에 unit/slice test 만들 때, AI는 조합 폭발을 잘 만든다. 입력 5개 × 상태 4개 = 20개 케이스를 기계적으로 생성한다. 그런데 그중 진짜 중요한 5개 — "ReviewLog가 Card보다 늦은 시각이면 안 된다", "soft delete된 Card는 ReviewSession에 들어오면 안 된다" 같은 — 를 골라내는 건 도메인 이해다. AI에게 맡기면 모든 케이스를 비슷한 비중으로 다뤄서 진짜 중요한 게 묻힌다.

→ 권장 워크플로우:
1. 사람이 invariant 5~10개를 한 줄씩 적음
2. AI에게 "이 invariant 각각에 대해 테스트 시나리오 풀어줘"
3. 사람이 우선순위 ★★★ 표시
4. AI가 코드화

7-5. PR Description / Commit Message

〔사람〕
- Why (의도, 배경)            → 리뷰어가 가장 보고 싶은 부분 (A5)
- 의도적으로 안 한 일         → "여기 리팩토링 안 한 이유" (A2)
- Trade-off 인정              → "지금은 이렇게, 다음엔 이렇게" (A2)
- 리뷰어에게 묻고 싶은 지점   → "이 부분 의견 듣고 싶음" (A2)

〔AI〕
- What (변경 파일/함수 요약)
- How (기술적 구현 요약)
- Diff 기반 changelog
- Conventional Commit 포맷
- Migration/Breaking change 체크리스트

가장 흔한 실수 지점이다. Claude Code로 작업한 PR에 AI 자동 생성 description을 그대로 두면, Why가 비어 있고 What만 잔뜩 있는 PR이 된다. 본인은 "도메인 정합성 위해 이름 바꿨다"가 진짜 이유인데, AI 생성문은 "Renamed AxisAction to AxisTopic across 17 files"만 나열한다. 리뷰어 눈엔 "기계적 변경"으로만 보인다.

7-6. CLAUDE.md / Rules 파일

〔사람〕
〔P0〕 절대 위반 금지 규칙       → "이 파일은 AI가 못 건드린다" (A1, A2)
〔P0〕 아키텍처 불변식           → "Repository는 4-layer port-adapter 유지" (A1)
〔P0〕 도메인 용어 사전          → Ubiquitous Language 못 박기 (A2, A4)
〔P1〕 우선순위 (어느 컨벤션이 더 강한가)

〔AI〕
〔P1〕 코드 스타일 일관성 검증
〔P2〕 형식 정돈, 200줄 제한 맞추기
〔P2〕 docs/와 rules/의 위치 정합성 점검

CLAUDE.md는 AI에게 내 의지를 전달하는 문서라서, AI가 자기 스스로 갱신하게 두면 점진적으로 약해진다. AI는 본능적으로 "유연한, 케이스별 판단" 같은 표현을 좋아하는데, 이게 절대 규칙을 무력화한다.

8. AI에게 맡겼을 때의 실패 모드 6가지

작업하면서 여러 번 데였다. 지금까지 발견한 패턴.

[F1] 사후 합리화 (post-hoc rationalization)
  → 결정이 있고 나면 AI는 무한히 그럴듯한 이유를 만들어냄
  → 진짜 Why가 묻힘
  → 대응: Decision/Why를 사람이 먼저, AI는 그 뒤만 채움

[F2] Plausible-sounding 단어 오염
  → AI는 "확장성/유연성/유지보수성" 같은 부드러운 단어를 좋아함
  → 결정의 날카로움이 무뎌짐
  → 대응: 사람이 한 줄 결론을 강한 동사로 미리 박음

[F3] 일관성 흉내 (잘못된 패턴 복제)
  → 기존 문서를 본떠 새 문서 만들 때, 잘못된 패턴까지 복제
  → 대응: 신규 BC 추가 시 사람이 "이 부분은 다르게 가자" 명시

[F4] 빈 칸 채우기 강박
  → 모르는 부분도 비워 두지 못하고 채워 넣음
  → "TBD"가 사라짐
  → 대응: 명시적으로 "모르는 건 ⚠️ 표시하고 비워 둬"라고 지시

[F5] Balanced 문서 만들기
  → AI는 양쪽 의견을 균형 있게 제시하려는 경향
  → 결정 문서인데 결정이 안 보임
  → 대응: ADR은 "Decision-first" 포맷 강제

[F6] 컨텍스트 깊이 부족 노출
  → 팀 히스토리, 과거 사고, 사내 정치 등 모름
  → 그걸 모르는 채로 추천을 내놓음
  → 대응: 사람의 맥락 주입 없이 ADR 생성 금지

09. 실전 운영 5원칙

〔원칙 1〕 Decision-first, Expansion-second
   → 사람이 한 단락 손글씨처럼 결정+이유 적음
   → AI는 그 뒤 Context/Alternatives/형식만 부풂
   → 적용: ADR, PR description, 도메인 모델링

〔원칙 2〕 AI는 형식, 사람은 내용
   → 같은 정보의 markdown→OpenAPI 변환은 AI okay
   → 정보 자체의 Truth는 사람이 grounding
   → 적용: API Spec, 테스트 코드 생성

〔원칙 3〕 Invariant 5~10개는 사람이 직접
   → BC마다 깨지면 안 되는 규칙 5~10개는 사람 손으로
   → 나머지는 그 위에 쌓는 것
   → 적용: Domain Doc, Test Modeling, CLAUDE.md

〔원칙 4〕 AI 출력에 ⚠️ 마커 강제
   → AI가 추측한 부분은 ⚠️ 표시하라고 시스템 프롬프트로 박음
   → 사람이 검증해야 할 곳을 시각적으로 식별
   → 적용: 모든 doc 생성 시

〔원칙 5〕 Why를 묻는 자기 점검
   → 문서 작성 후 본인이 "왜 이렇게 정했지?"에 한 줄 답하기
   → 답이 안 나오면 그 부분은 사후 합리화일 가능성
   → 적용: ADR, Roadmap 우선순위

마무리

처음 질문 — "docs를 living 방식으로 운영해도 괜찮은가?" — 에 대한 답을 정리하면 이렇다.

- Top-down과 Living은 다른 trade-off curve를 가짐
- 절대 우위는 없음, 작업 성격에 따라 적합한 영역이 다름
- 도메인 모델링 + 학습 + 하네스 운영 → Living이 유리
- 외부 계약 + 결정 history + onboarding → Top-down이 유리
- 그래서 답은 "둘을 layered로 섞어 쓴다"
- Frozen Core (Layer 1) + Living Working Set (Layer 2) + Story-local Harness (Layer 3)

그리고 어느 layer에 있든 사람이 쥐어야 할 부분과 AI에게 맡길 부분을 명확히 분리해야 한다. 5축 기준으로:

Why, Decision, Invariant, BC 경계, 외부 계약 → 사람
What, How, 보일러플레이트, 형식 변환, 시나리오 expansion → AI

한 줄로 줄이면:

AI는 내가 무엇을 결정했는지를 잘 표현하지만, 내가 왜 결정했는지는 만들어내지 못한다. Doc-driven workflow의 Doc은 결국 그 Why를 보존하기 위해 있다.

Living docs가 하네스 운영에 잘 맞았던 이유는 모듈성·컨텍스트 가벼움·속도 동기화·수정 비용·실험 친화성·합성 노이즈 감소가 한꺼번에 정렬됐기 때문이다. 다만 이 강점은 작은~중간 scale에서 가장 크고, 큰 scale에선 정합성 비용이 따라온다. Layered 구조는 그 강점을 살리면서 비용을 가두는 구조적 답이다.

ThirdTool에 적용하면서 계속 다듬는 중이다. 여기 적은 trade-off, 5축, 실패 모드, 5원칙은 지금 시점의 결론이고, 이 글 자체도 layered 구조로 보면 Layer 2 — 진화 중인 living working note — 에 가깝다. 안정화되면 다음 글에서 다시 정리해볼 생각이다.

junsung kim

edit하는 개발자! story 있는 삶

이전 포스트

[Third Tool] 도메인 서비스 도입하기

다음 포스트