research

맥락/히스토리 기록 방법론

맥락/히스토리 기록 방법론

핵심 긴장: 인간 가독성 vs. LLM 가독성

Mermaid는 인간이 큰 흐름을 파악하기엔 좋지만, LLM이 "왜 이 결정을 했지?"를 추론하는 데는 텍스트가 더 효율적이다.

용도가 다르다:

| 형식 | 답하는 질문 | 적합한 내용 | |---|---|---| | Mermaid / 다이어그램 | 무엇이 무엇과 연결되는가 | 서비스 관계, 데이터 흐름, 레이어 구조 | | 텍스트 (ADR) | 왜 이 결정을 했는가 | 라이브러리 선택, 아키텍처 결정 근거 | | 코드 + 주석 | 어떻게 동작하는가 | 함수 레벨, 엣지 케이스 |

셋 다 필요하지만, 분리해야 어느 파일을 봐야 하는지 명확하다.

ADR — "왜"를 기록하는 표준 방법론

Architecture Decision Record. 결정 자체뿐 아니라 컨텍스트, 고려한 대안, 결과까지 기록한다.

Michael Nygard 최소 구조

# ADR-0001: SQLite를 주 DB로 선택

## Status
Accepted

## Context
어떤 문제가 있었나? 어떤 제약이 있었나?

## Decision
무엇을 선택했나? 왜?

## Consequences
### Positive
- 서버 프로세스 불필요, 파일 하나로 관리
### Negative
- 동시 쓰기 제한

핵심 원칙

  • ADR은 결정을 기록하는 것, 구현 세부사항이 아니다
    • ✅ "SQLite를 선택한 이유"
    • ❌ "SQLite 설정 방법" (이건 다른 문서)
  • 한 번 accepted되면 수정하지 않는다
  • 변경이 생기면 새 ADR이 기존 것을 supersede한다
  • 대안을 반드시 명시 — "A 대신 B를 선택했고, A를 안 선택한 이유는..."

LLM 소비를 위한 ADR 설계

LLM이 잘 읽는 ADR의 특징:

  1. 대안 명시: LLM이 미래에 비슷한 결정을 할 때 참조 가능
  2. 코드와 연결: 코드 주석에서 ADR로 링크 ("ADR-0003 참고")
  3. 일관된 섹션 헤딩: LLM이 파싱하기 쉬움

실용적인 계층 구조

docs/adr/              →  결정의 "왜" (ADR)
                           adr-0001-why-sqlite.md
                           adr-0002-why-sqlalchemy.md

README / AGENTS.md     →  구조의 "무엇" (Mermaid + 개요)
                           큰 흐름, 레이어 관계

코드 주석 / docstring  →  구현의 "어떻게"
                           함수 레벨 설명, 엣지 케이스

claude-progress.txt    →  진행의 "지금까지"
                           히스토리 + 현재 상태

Mermaid의 현실적인 적용 범위

효과적인 용도:

  • 서비스 간 관계
  • 데이터 흐름
  • 레이어 구조 (AGENTS.md의 "지도" 역할)

비효율적인 용도:

  • 함수 내부 로직
  • 라이브러리 선택 이유
  • 세부 결정 근거

→ Mermaid는 구조 파악용 지도로 한정하고, 세부 결정은 ADR 텍스트로 관리하는 것이 현재 가장 정립된 방식.

관련 개념

대화 중 방향 전환 — Skill layer 관리

문제

대화 중 방향이 바뀌면 기존 ADR이 현실과 멀어진다.

해결 — ADR supersede 패턴

기존 ADR을 수정하지 않는다. 새 ADR을 만들고 기존 것을 supersede.

# ADR-0007: PostgreSQL로 전환

## Status
Accepted — supersedes ADR-0001

## Context
초기엔 SQLite를 선택했다 (ADR-0001).
v2에서 동시 접근 요구사항이 생겼다.

## 왜 방향이 바뀌었는가
[설계하자] 세션에서 v2 요구사항 검토 중 발견. 2025-11-20.

ADR-0001 상단에:

## Status
~~Accepted~~ → Superseded by ADR-0007

ADR은 불변 히스토리다. 과거를 지우지 않고 "그때는 그랬고, 지금은 이렇다"를 기록.

실용적 워크플로우

대화 중에 즉시 ADR을 만들기 어렵다. 대화 흐름 안에서 결정이 자연스럽게 흘러가기 때문.

대화 중 방향 전환 발생
    ↓
대화 직후 — decisions.md에 한 줄 메모
  "2025-11-20: SQLite → PostgreSQL, 이유: 동시 접근"
    ↓
코딩 전 — 정식 ADR로 승격
    ↓
기존 ADR supersede 처리

decisions.md가 ADR 초안 대기열 역할을 한다.

AGENTS.md 포인터도 업데이트

- DB 관련: ~~docs/adr/0001~~ → docs/adr/0007-why-postgresql.md

GC agent가 "ADR-0001이 superseded인데 AGENTS.md가 아직 그걸 가리키고 있다"를 찾아내는 케이스. → AC, GC, ADR supersede 패턴이 여기서 연결된다.

← research 목록으로홈으로