코딩 에이전트에게 필요한 것은 더 많은 컨텍스트가 아니라 코드 브레인(Code Brain)입니다

대부분의 코딩 에이전트 실패는 약한 모델에서 시작되지 않습니다. 그것은 저장소 컨텍스트 (repository context)의 부재에서 시작됩니다.

에이전트는 이상한 추상화 (abstraction)를 설명하는 아키텍처 결정 사항을 찾지 못합니다. 오래된 패키지에 숨겨진 컨벤션 (convention)을 놓칩니다. 어제의 발견을 재사용 가능한 프로젝트 지식으로 전환하는 사람이 아무도 없기 때문에 똑같은 파일들을 다시 읽습니다.

LangChain의 오픈 소스 OpenWiki는 유용하고 의도적으로 지루한 접근 방식을 취합니다. 저장소를 위한 로컬 Markdown 위키를 생성하고, 이를 최신 상태로 유지하며, 코딩 에이전트가 코드베이스를 처음부터 탐색하기 전에 이를 참조하도록 가르치는 것입니다.

그것은 마법 같은 메모리가 아닙니다. 유지 관리되는 컨텍스트 아티팩트 (context artifact)입니다. 많은 팀에게 있어 그 차이가 핵심입니다.

OpenWiki가 실제로 변화시키는 것

OpenWiki는 저장소를 위한 코드 브레인 (Code Brain) 모드를 가지고 있습니다. 이 CLI는 openwiki/ 디렉토리에 문서를 초기화하고 업데이트할 수 있습니다. 또한 프로젝트는 저장소 루트에 AGENTS.md 및 _CLAUDE.md_를 유지하여, 호환 가능한 코딩 에이전트들이 컨텍스트를 찾을 때 위키를 사용하도록 지시합니다.

중요한 설계 선택은 메모리를 검사할 수 있다는 점입니다:

• Markdown 파일이 불투명한 벡터 데이터베이스 (vector database) 내부가 아니라 프로젝트와 함께 존재합니다.
• 변경 사항을 풀 리퀘스트 (pull request)로 검토할 수 있습니다.
• 저장소가 변경될 때 위키를 다시 생성할 수 있습니다.
• 에이전트는 수정을 시작하기 전에 코드베이스의 안정적인 지도를 얻습니다.

트레이드오프 (tradeoff) 또한 똑같이 중요합니다: 생성된 문서가 오래되거나 확신을 가지고 틀릴 수 있습니다. 코드 브레인은 업데이트 경로가 엔지니어링 워크플로 (engineering workflow)의 일부일 때만 유용합니다.

시도해 보기 안전한 작은 워크플로

메인 체크아웃이 아닌 브랜치에서 시작하세요:

git switch -c chore/openwiki-refresh
openwiki --init
openwiki --update
...

마치 주니어 엔지니어가 작성한 것처럼 디프 (diff)를 읽으세요. 다음 사항을 확인하십시오:

1. 공개적으로 문서화해서는 안 되는 명령(Commands) 또는 배포 세부 정보.
2. 현재 소스 트리(source tree)에 의해 뒷받침되지 않는 주장.
3. 생성된 파일과 사람이 작성한 가이드 사이의 경계 누락.
4. 에이전트가 파괴적인 명령(destructive commands)을 실행하게 만들 수 있는 지침.
5. 절약되는 것보다 더 많은 컨텍스트(context) 비용을 발생시키는 크고 노이즈가 많은 페이지.

결과가 유용하다면, 이를 커밋(commit)하고 업데이트 작업(update job)을 추가하세요. 저장소의 README에는 문서가 변경될 때 풀 리퀘스트(pull request)를 생성할 수 있는 CI 워크플로우 패턴이 표시되어 있습니다. 해당 PR을 검토 가능한 상태로 유지하세요. 생성된 아키텍처(architectural) 주장을 조용히 머지(merge)하지 마십시오.

에이전트가 위키(wiki)를 의도적으로 사용하게 만들기

생성된 파일이 모든 에이전트를 자동으로 개선하는 것은 아닙니다. 저장소 가이드에서 계약(contract)을 명시적으로 만드세요:

# 에이전트 컨텍스트 (Agent context)

코드를 변경하기 전에:
...

이렇게 하면 위키는 신탁(oracle)이 아닌 시작 지점으로서의 지도(map)가 됩니다. 에이전트는 여전히 구현 내용을 조사하고 테스트를 실행해야 합니다.

코드 브레인(code brain) 추가 후 측정해야 할 것

생성된 페이지의 수로 성공을 측정하지 마세요. 워크플로우(workflow)를 측정하세요:

도입 전후에 동일한 작은 작업 세트를 사용하세요. 모델, 프롬프트(prompt), 저장소 리비전(repository revision), 수락 검사(acceptance checks)를 실질적으로 가능한 한 일정하게 유지하세요. 토큰(token) 수가 적거나 트레이스(trace)가 짧은 것이 개발자 생산성이 높다는 증거는 아닙니다. 이는 단지 에이전트가 필요한 검증을 건너뛰었음을 의미할 수도 있습니다.

이 패턴이 적합한 경우

코드 브레인은 저장소가 다음과 같은 상황일 때 가장 유망합니다:

• 여러 서비스 또는 패키지(packages)가 있는 경우;
• 단일 파일만으로는 추론하기 어려운 컨벤션(conventions)이 있는 경우;
• 반복적인 온보딩(onboarding) 또는 유지보수 작업이 있는 경우;
• 에이전트가 동일한 아키텍처를 반복적으로 탐색하는 경우;
• 생성된 문서를 검토할 의사가 있는 팀이 있는 경우.

README와 테스트가 이미 시스템을 설명하고 있는 아주 작은 프로젝트의 경우에는 매력이 덜할 수 있습니다. 또한, 이 방식이 권한 부여 (Authorization), 샌드박싱 (Sandboxing), 프롬프트 인젝션 (Prompt Injection), 불안정한 테스트 (Flaky tests), 또는 부실한 작업 명세 (Poor task specifications) 문제를 해결해 주는 것도 아닙니다. 이러한 요소들은 여전히 별도의 제어 수단으로 남습니다.

실무 체크리스트

생성된 에이전트 컨텍스트 (Agent context)를 공유 저장소에 넣기 전에 다음 사항을 질문해 보세요:

• 모든 페이지가 파일, 테스트, 또는 승인된 인간의 노트로 추적 가능한가?
• 오래된 페이지의 정리 책임은 누구에게 있는가?
• CI (지속적 통합)가 메인 브랜치를 조용히 변경하는 대신 검토 가능한 PR (Pull Request)을 생성하는가?
• 비밀 정보 (Secrets)와 민감한 소스 발췌본이 제외되었는가?
• 위키가 코드와 충돌할 때 에이전트에게 폴백 (Fallback) 수단이 있는가?
• 개발자가 생성기와 싸우지 않고도 페이지를 삭제하거나 수정할 수 있는가?
• 작업 결과가 컨텍스트 검색 (Context retrieval)과 별개로 측정되는가?

OpenWiki의 흥미로운 가설은 에이전트에게 무한한 메모리가 필요하다는 것이 아닙니다. 에이전트에게 필요한 것은 자신이 변경하려는 소프트웨어에 대한 압축된, 로컬의, 검토 가능한 지도라는 점입니다.

이는 "모든 것을 기억하라"는 요구보다 훨씬 관리하기 쉬운 능력입니다.

여러분은 프로덕션 저장소에 생성된 openwiki/ 디렉토리를 신뢰하시겠습니까, 아니면 에이전트 컨텍스트를 별도의 인간이 관리하는 핸드북에 보관하시겠습니까? 어떤 검토 규칙을 요구하시겠습니까?

출처

• OpenWiki repository and CLI documentation
• LangChain: OpenWiki Brains, proactive memory for AI agents