아키텍처 규칙을 레포지토리에 보관하세요. AI와 신입사원 모두 같은 파일을 읽게 하세요.

몇 주 전, 저는 에이전트가 하나의 기능을 멋지하게 구축하는 것을 지켜봤습니다.

클린 코드(Clean code). 테스트 통과. 제가 요청한 것 그대로 수행했습니다.

세션이 세 번 지나자, 저는 같은 서비스를 열어보고는 그것을 알아보지 못했습니다. 아무것도 잘못된 것은 없었습니다. 모든 개별 결정은 합리적이었습니다. 하지만 이것들이 쌓여서, 마치 제가 설계하지 않았을 법한 곳으로 코드베이스를 조용히 이끌고 갔습니다.

그때 깨달았습니다. 문제는 모델이 아니었습니다. 모델은 훌륭했습니다. 문제는 매 세션이 '제로(zero)'에서 시작한다는 것이었습니다. 제가 보호해 오던 경계에 대한 기억도 없고, 어떤 패턴이 핵심적인지 아는 것도 없으며, 3주 전 제가 기록하지 않은 이유로 내린 트레이드오프(trade-off)가 무엇인지 전혀 모르는 상태였습니다.

저는 이 정확한 실패를 전에 경험한 적이 있었습니다. 단지 사람들과 함께일 때였습니다.

문서에 접근하지 못한 신입사원

여러분도 아는 버전입니다. 누군가 합류합니다. 그들은 똑똑하고, 첫 주 안에 작동하는 무언가를 배포하지만 — 아무도 알려주지 않은 암묵적인 규칙을 깨뜨립니다. 그들의 잘못이 아닙니다. 그 규칙은 제 머릿속에 있거나, 지난 3월의 Slack 스레드에 있거나, 혹은 가장 오래 일한 사람의 근육 기억 속에 존재했습니다.

그래서 저희는 그것을 설명합니다. 그리고 다음 사람에게 또다시 설명합니다. '왜(why)'라는 부분이 결코 영구적으로 저장되는 곳이 없었습니다. 그저 필요할 때마다, 잘못되게 재설명될 뿐이었습니다.

AI 세션은 총명하고 빠르지만 완전한 기억상실증을 겪는 신입사원과 같습니다. 매번 그렇습니다. 아침마다 새로운 채팅 창에 코드베이스를 다시 설명하는 것은 지치고, 솔직히 압박감 속에서는 절반도 잊어버릴 것 같았습니다.

같은 문제입니다. 저는 단지 그것을 두 번 해결하고 있었던 것입니다.

진실의 원천 하나, 청중 둘

저희에게 이것을 고쳐준 변화는 이렇습니다. AI 에이전트가 코드베이스를 망치지 않기 위해 필요한 컨텍스트(context)는 첫날 신입 엔지니어가 필요로 하는 것과 _동일한 컨텍스트_라는 것입니다.

비슷한 것이 아닙니다. 같은 것입니다.

어떤 패턴이 의도적인지. 경계가 어디에 있고 왜 그것을 넘어서는 것이 비용을 초래하는지. 여기서 '완료(done)'가 무엇을 의미하는지. 어떤 결정은 확정되었고, 어떤 것은 여전히 논의 중인지. 인간은 이것이 있어야 무언가를 기여하면서도 망치는 것을 방지할 수 있습니다. 에이전트 역시 이것이 있어야 무언가를 기여하면서도 망치는 것을 방지할 수 있습니다.

그래서 우리는 그것을 머릿속에 담아두는 것을 멈추고 레포지토리에 보관하기 시작했습니다. 일반 마크다운 파일로요. 커밋하고, 설명하는 코드와 함께 버전을 관리합니다.

service-payments/
├── CLAUDE.md          # 이 서비스가 어떻게 작동하며, 왜 그런지
├── src/
...

루트 디렉터리에 CLAUDE.md (또는 도구가 읽도록 설정한 규칙에 따라 AGENTS.md)를 두면 프로젝트 전체의 원칙을 담을 수 있습니다. 자체적인 실제 규칙을 가진 각 서비스는 해당 서비스만의 파일을 갖게 됩니다. 에이전트가 그 서비스를 열 때, 이 파일이 자동으로 로드됩니다. 사람이 그 서비스를 열 때도 마찬가지로, 사람이 실제로 읽을 수 있도록 작성된 동일한 파일이 바로 그 자리에 놓여 있습니다.

하나의 파일. 두 명의 독자. 동기화할 필요가 없습니다. 오직 하나만 존재하기 때문입니다.

파일에 실제로 들어가야 할 내용

대부분의 팀들이 잘못하는 부분이 바로 여기입니다. 그들은 당연한 것들, 즉

방치하면 파일은 부패합니다. 더 이상 유효하지 않은 규칙은 규칙이 없는 것보다 더 나쁩니다. 이는 두 대상(AI와 사람) 모두에게 동시에 잘못된 것을 가르치기 때문입니다. 따라서 이 파일들은 코드처럼 리뷰되어야 합니다. 왜냐하면 이제 그것들은 코드이기 때문입니다. 결정된 사항이 변경되면, 동일한 PR (Pull Request) 내에서 파일도 함께 변경됩니다. 이것이 오버헤드(Overhead)처럼 느껴진다면, 그것은 이미 반복적인 설명 과정에서 지불하고 있었던 오버헤드가 가시화된 것뿐입니다.

그리고 완벽한 설정이 갖춰질 때까지 AI 도구 사용을 중단한 것은 아닙니다. 핵심은 에이전트 (Agent)를 통제하는 것이 아닙니다. 결정이 내려질 당시 그 자리에 없었던 누군가 — 혹은 무언가 — 에 의해 점점 더 많이 작성되고 있는 코드베이스에, 나의 장기적인 사고가 여전히 반영되어 있는지 확인하는 것입니다.

파일 하나로 부족해지는 시점

마크다운 (Markdown) 파일은 작동하다가 어느 순간 한계에 부딪힙니다. 하나의 서비스와 몇 가지 규칙만 있다면 CLAUDE.md가 완벽합니다. 하지만 이것을 수십 개의 서비스로 확장하면, 규칙을 '관리하는 것' 자체가 업무 전체가 되어버립니다. 규칙은 그것이 설명하는 코드로부터 멀어집니다. 기능 뒤에 숨겨진 "이유(why)"는 사양서 (Spec), 티켓 (Ticket), PR (Pull Request) 설명, 그리고 6주 뒤에는 아무도 찾을 수 없는 대화 속에 흩어져 버립니다. 단일 파일로는 이를 따라갈 수 없으며, 오래된 규칙은 독자 모두에게 동시에 잘못된 것을 가르치게 됩니다.

그러한 부패 현상이 저로 하여금 Bodhiorchard를 만들게 했습니다. 이는 제가 독립적으로 작업해 온 오픈 소스 자가 호스팅 (Self-hosted) 프로젝트입니다 (Apache 2.0, Claude Code에서 실행). 파일 방식과 같은 아이디어지만, 이를 더 발전시킨 것입니다. 하나의 기능에 대한 지식이 티켓 여기저기에 흩어져 있는 대신, 해당 기능에 관한 모든 것—사양서 (Spec), 기술 사양서 (Tech Spec), 테스트 계획 (Test Plan), 수락 기준 (Acceptance Criteria), 전체 이력—이 실제 코드와 연결된 하나의 살아있는 문서에 담깁니다. 그리고 지식 계층 (Knowledge layer)은 코드 및 해당 문서들과 자동으로 동기화되어 최신 상태를 유지하므로, 사람이 의미론적으로 검색할 수 있을 뿐만 아니라 모든 에이전트 (Agent)의 프롬프트 (Prompt)에 직접 입력됩니다.

그것이 제가 가장 중요하게 생각하는 부분입니다. 업데이트해야 한다는 사실을 기억해야 하는 위키(Wiki)가 아닙니다. 작업이 이미 일어나는 곳에 연결되어 있기 때문에 최신 상태를 유지하는 위키입니다. Confluence는 작성하는 날 바로 노후화됩니다. 하지만 이것은 그렇지 않습니다. 왜냐하면 누구의 업무도 그것을 수동으로 유지하는 것이 아니기 때문입니다.

원칙은 변하지 않았습니다. 하나의 진실된 원천 (One source of truth), 두 개의 대상. 저는 그저 동기화 엔진 (Sync engine) 역할을 하는 것에 지쳤을 뿐입니다.

무엇이 변했는가

설명하는 일이 줄어들었습니다. 이것이 지루하지만 실제적인 승리입니다.

새로운 엔지니어들은 에이전트 (Agent)가 읽는 것과 동일한 파일을 읽습니다. 그리고 모든 것을 문자 그대로 받아들이는 기계를 위해 작성한 문서가 정말 좋은 온보딩 (Onboarding) 문서가 된다는 사실이 밝혀졌습니다. 가정된 맥락이 없습니다. "금방 익히게 될 거예요"라는 말도 없습니다. 그저 사물의 실제 형태가 있을 뿐입니다.

그리고 드리프트 (Drift, 괴리)가 느려졌습니다. 에이전트가 더 똑똑해졌기 때문이 아니라, 어떤 벽이 하중을 견디는 벽인지 마침내 알게 되었기 때문입니다.

저는 예전에 코드베이스 (Codebase)가 코드 안에 존재한다고 생각했습니다. 그렇지 않습니다. 그 절반은 코드
주변의 결정 사항들에 존재합니다. 그리고 수년 동안 저는 그 절반을 정확히 단 한 명의 독자만이 접근할 수 있는 제 머릿속에 담아두었습니다.

이제 그것은 레포지토리 (Repo)에 있습니다. 인간이든 아니든, 모두가 접근할 수 있는 곳에 말이죠.

만약 당신이 AI에게 코드의 상당 부분을 작성하도록 허용하고 있다면: 당신의 코드베이스 규칙은 현재 실제로 어디에 있습니까? 그리고 누가 그것을 읽을 수 있습니까?