하네스 엔지니어링 9단계 베스트 프랙티스 #2. Code Wiki 작성

시리즈 맥락 복기

앞서 #0에서는 프로세스 지도를, #1에서는 에이전트가 지켜야 할 규칙을 준비했습니다. 그런데 규칙만 있으면 AI는 "이 코드가 왜 이렇게 짜였는지"를 모릅니다. 코드를 읽으면 파악되는 것(함수 시그니처)과 코드에서 절대 읽히지 않는 것(순서 제약, 설계 의도)은 전혀 다르기 때문입니다.

1. #0 업무 프로세스 매핑
2. #1 프로젝트 규칙 설정
3. #2 Code Wiki 작성 ← 이번 편
4. #3 Skill 정의
5. ... (#8까지)

이 단계의 의미 — 하네스에서 Code Wiki가 하는 일

Step 2는 에이전트에게 "이 프로젝트의 지형도"를 건네주는 단계입니다. 말이 익숙하지 않은 길을 달릴 때 넘어지듯이, AI도 맥락이 없는 코드베이스에서는 엉뚱한 위치에 기능을 붙이거나, 이미 결정된 사항을 뒤집으려 합니다. Code Wiki는 이런 사고를 예방하는 예방 접종에 가깝습니다.

해결하려는 문제

• AI가 새 기능을 엉뚱한 모듈에 넣는 문제: 파이프라인 순서를 모르니, 필터 앞에 그룹핑을 넣는 식의 실수가 발생합니다.
• 도메인 용어 오해: PhotoEvent와 Trip이 비슷해 보인다고 같은 로직으로 처리해 버립니다.
• 결정 번복: "OpenAI API가 더 낫지 않나요?" 같은 이미 끝난 논의를 매번 반복합니다.

효과 — 임팩트는 어느 정도인가

Code Wiki 3종 세트를 1회 작성하는 데 1~2시간이 들지만, 이후 AI가 리팩토링을 제안할 때마다 이 문서를 참조하게 되어 재작업이 크게 줄어듭니다. 특히 "기존 선택의 이유"를 기록한 ADR은 같은 논의를 반복하지 않게 해주는 보험 같은 문서입니다.

Code Wiki 3종 세트

문서	담는 내용	AI가 얻는 것
아키텍처	모듈 간 데이터 흐름 + "왜 이렇게 나눴는지"	새 기능을 어디에 붙여야 하는지 판단
도메인 용어 사전	코드에서 쓰이는 비자명한 개념 정의	변수명·함수명의 의도를 오해하지 않음
의사결정 기록 (ADR)	기술 선택의 이유 + 검토한 대안	기존 결정을 뒤집지 않음

① 아키텍처 — 순서 제약을 그려라

AI는 코드만 읽으면 각 모듈이 뭘 하는지는 알아내지만, "A 다음에는 반드시 B가 와야 한다"는 순서 제약은 읽어낼 수 없습니다. 이 제약을 흐름도로 그려두면 에이전트가 맥락을 잃지 않습니다.

문서에는 흐름도만이 아니라 제약 조건도 같이 적어야 합니다.

• Filter를 거치지 않은 데이터는 Grouper에 넣으면 안 된다 (의도치 않은 항목 포함)
• Narrator는 GPU를 사용하므로 반드시 스케줄러 acquire/release로 감싼다
• 모든 모듈은 Record dataclass를 주고받는다. 필드 추가 시 파이프라인 전체 검토 필요

② 도메인 용어 — 이름이 품고 있는 맥락을 적어라

클래스명/변수명은 기술적 의미만으로는 해석되지 않습니다. 예를 들어 PhotoEvent라는 이름을 AI는 "사진 이벤트"로 추측하지만, 실제로는 "48시간 이내로 묶인 사진 그룹. 3장 미만은 일상으로 병합"이라는 도메인 규칙이 숨어 있을 수 있습니다.

코드상 이름	AI 추측	실제 의미
PhotoEvent	사진 이벤트	48시간 이내로 묶인 그룹. 3장 미만은 "일상"으로 병합
Trip	여행	여행 단위 묶음. Event와 달리 날짜별로 재분리
Segment	구간	Trip 내 시간대별 그룹. 편집의 최소 단위
narrative	설명문	LLM이 생성한 스토리. 후처리 4단계를 거친 결과물

이 사전이 있으면 AI가 PhotoEvent를 수정하다가 Trip 로직을 잘못 섞는 사고를 예방할 수 있습니다.

③ ADR — 기술 선택의 이유를 기록하라

ADR(Architecture Decision Record)은 "이 기술을 왜 선택했는가"를 남기는 짧은 문서입니다. AI가 "더 좋은 방법이 있다"고 제안할 때, ADR이 있으면 "이미 검토하고 결정한 것"임을 알립니다.

ADR의 고전적인 서식은 Michael Nygard가 제안한 4섹션 구조입니다. 이 시리즈 이전 편인 Docs-as-Code로 사이드 프로젝트 문서화하기 — 코드 위키 실전 적용기에서도 동일한 포맷을 권장했으니, 여기서도 같은 형식을 유지합니다.

섹션	담는 내용
Status	Proposed / Accepted / Deprecated / Superseded 중 하나
Context	어떤 상황이었나 — 결정을 내려야 했던 배경·제약·문제
Decision	무엇을 결정했나 — 실제 택한 방안과 핵심 근거
Consequences	결과와 트레이드오프 — 이 결정으로 얻은 것, 포기한 것, 검토하고 버린 대안

# ADR-002: 서사 생성에 로컬 LLM을 사용한다

## Status
Accepted

## Context
수천 개 항목의 서사를 생성해야 한다.
개인 자료라 외부 API로 전송하면 프라이버시 이슈가 생긴다.
GPU는 이미 다른 워크로드에서 확보해 둔 자원이 있다.

## Decision
로컬 vLLM 서버로 서사를 생성한다.
continuous batching을 활용해 대량 처리에 최적화한다.

## Consequences
+ 비용 제로 (신규 외부 요금 발생 없음)
+ 프라이버시 보호 (메타데이터가 외부로 나가지 않음)
+ 배치 처리 시 처리량이 크게 상승
- 모델 품질은 상용 API 대비 다소 낮을 수 있음
- GPU 자원 관리(스케줄러·선점) 복잡도 증가

### 검토하고 버린 대안
- 외부 API: 비용 + 프라이버시 이슈
- Ollama: 단건 처리만 지원 → 배치 비효율

한 결정에 ADR 한 개, 10~20줄이면 충분합니다. 4섹션 중 특히 중요한 것은 Consequences입니다. 여기에 "검토하고 버린 대안"까지 적어두지 않으면, AI가 "OpenAI API가 더 간단하지 않나요?" 같은 제안으로 같은 논의를 몇 번이고 다시 시작합니다.

자주 빠지는 실수

• 함수 시그니처 나열: AI는 코드를 직접 읽을 수 있으므로 이런 정보는 문서에 중복입니다.
• "일단 다 적어두자": 5쪽 이상 긴 문서는 에이전트가 맥락을 잃습니다. 핵심 제약과 결정만.
• 오래된 채로 방치: 코드가 바뀔 때 Wiki도 같이 갱신하는 정책이 필요합니다 (프로젝트 규칙에 명시).

다음 단계 예고 — Step 3 Skill 정의

지도(#0), 규칙(#1), 지형도(#2)를 갖췄다면, 이제는 에이전트가 실제로 실행할 작업 단위를 정의할 차례입니다. 다음 편에서는 SKILL.md에 트리거 키워드·워크플로우·환경변수를 한 파일에 담는 방법을 다룹니다.

한 줄 요약: "Code Wiki는 코드가 말하지 않는 것을 말해주는 문서다."

---

이 글은 생성형 AI의 도움을 받아 작성되었습니다. 원본 자료를 기반으로 AI가 초안을 생성하고, 작성자가 검토·편집하였습니다.