아프니까 개발자다 아프니까 개발자다

시리즈 맥락 복기앞서 #0에서는 프로세스 지도를, #1에서는 에이전트가 지켜야 할 규칙을 준비했습니다. 그런데 규칙만 있으면 AI는 "이 코드가 왜 이렇게 짜였는지"를 모릅니다. 코드를 읽으면 파악되는 것(함수 시그니처)과 코드에서 절대 읽히지 않는 것(순서 제약, 설계 의도)은 전혀 다르기 때문입니다.#0 업무 프로세스 매핑#1 프로젝트 규칙 설정#2 Code Wiki 작성 ← 이번 편#3 Skill 정의... (#8까지)이 단계의 의미 — 하네스에서 Code Wiki가 하는 일Step 2는 에이전트에게 "이 프로젝트의 지형도"를 건네주는 단계입니다. 말이 익숙하지 않은 길을 달릴 때 넘어지듯이, AI도 맥락이 없는 코드베이스에서는 엉뚱한 위치에 기능을 붙이거나, 이미 결정된 사항을 뒤집으려 합니다. ..

코드는 "무엇"을 보여주지만, "왜"는 보여주지 않는다git blame을 하면 누가, 언제 이 코드를 작성했는지는 알 수 있다. 하지만 당시 어떤 대안이 있었고, 왜 이 방법을 택했는지는 알 수 없다. 커밋 메시지에 "PostgreSQL → SQLite로 변경"이라고 적혀 있어도, 왜 PostgreSQL을 버렸는지, 어떤 트레이드오프를 감수했는지는 사라진다.이 간극을 메우는 문서가 ADR(Architecture Decision Record)이다. "이 프로젝트에서 왜 이런 선택을 했는가"를 짧고 구조화된 형식으로 기록한다.ADR의 기원: Michael Nygard는 누구인가ADR이라는 형식을 처음 제안한 사람은 Michael T. Nygard다. 2011년에 쓴 블로그 글 "Documenting Arch..

사이드 프로젝트에 문서가 없으면 생기는 일사이드 프로젝트를 몇 달 방치하다 다시 열면, 내가 짠 코드인데도 "이게 뭐였지?" 하게 된다. README에 설치 방법 세 줄 적어둔 게 전부라, 어디서부터 손대야 할지 감이 안 온다. 함수 이름으로 역할을 유추하고, git log로 당시의 의도를 추적하는 고고학이 시작된다.이건 혼자 작업해도 마찬가지고, AI 코딩 에이전트를 쓸 때는 더 심각하다. Claude Code나 Cursor 같은 도구에 "이 프로젝트 구조 파악해줘"라고 하면, 코드를 전부 읽긴 하지만 왜 이런 설계를 했는지는 코드만으로 알 수 없다. 결국 매 세션마다 같은 설명을 반복하게 된다.이 문제의 해법이 바로 코드 위키(Code Wiki)다. 코드와 함께 버전 관리되는, 살아있는 문서 체계.코..