Project Brain: Claude Code에 실제로 작동하는 메모리 부여하기

Claude Code를 사용하는 모든 개발자는 결국 동일한 벽에 부딪힙니다:

1. 프로젝트의 아키텍처 (Architecture)를 설명합니다.
2. 배포 설정 (Deployment setup)을 설명합니다.
3. 스택 (Stack) 선택 이유를 설명합니다.
4. 이미 구축된 내용을 요약합니다.
5. 알려진 함정 (Pitfalls)들을 나열합니다.

...그러고 나서 다음 날, 이 모든 과정을 다시 반복합니다. 더 나쁜 것은, 여러 프로젝트에 걸쳐 몇 시간 동안 작업하다 보면 Claude가 프로젝트 간의 세부 사항을 뒤섞기 시작한다는 점입니다.

핵심 문제는 능력이 아니라 메모리 (Memory)입니다. 지속적인 컨텍스트 (Context)가 없다면, 모든 세션은 제로 상태에서 시작됩니다. 현재의 "해결책"들은 다음과 같습니다:

• README 덤프 (The README Dump): 각 세션에 전체 문서를 붙여넣기 (토큰 비용이 많이 들고 유지 관리가 번거로움)
• 평면적인 노트 파일 (The Flat Notes File): 본인조차 탐색할 수 없을 정도로 커지는 거대한 마크다운 (Markdown) 문서
• 기억력 게임 (The Memory Game): Claude가 어떻게든 기억하기를 희망하기 (기억하지 못함)

Project Brain이 실제로 작동하는 방식

Project Brain은 다음과 같이 단순하지만 효과적인 패턴을 구현하는 Claude Code 스킬입니다:

.project-brain/
  index.md                          # 프로젝트 → 주제에 대한 가벼운 지도
  projects/
...

핵심 혁신은 기술적인 것이 아니라 구조적인 것입니다:

1. 인덱스 우선 탐색 (Index-first navigation): Claude는 세부 사항에 뛰어들기 전에 작은 인덱스(Index)를 먼저 읽습니다 (비용이 저렴하며, 필요할 때만 비용이 발생함)
2. 상태 추적 (Status tracking): ✓ 확인됨 (verified) vs ✗ 실패함 (failed) vs ⚠ 진행 중 (in-progress)을 통해 Claude는 무엇이 실제로 작동했는지 알 수 있습니다.
3. 버전 관리된 지식 (Versioned knowledge): 대체된 접근 방식은 덮어쓰여지는 것이 아니라 보존됩니다.

실제로 무엇을 해결하는가

성과에 대해 냉정하게 솔직해 봅시다:

1. 환각 (Hallucinations) 감소: 지도는 닻 역할을 합니다. 모델이 배포 방식을 지어내거나 한 프로젝트의 스택을 다른 프로젝트의 것으로 바꾸는 일이 중단됩니다.
2. 컨텍스트 고정 (Context anchoring): 프로젝트 간 전환 시 아키텍처가 뒤섞일 위험이 더 이상 없습니다.
3. 장기 메모리 (Long-term memory): 몇 달 만에 프로젝트로 돌아와도 모든 것을 다시 가르칠 필요가 없습니다.

토큰 절약 효과는 현재의 워크플로우(workflow)에 따라 달라집니다. 만약 현재 매 세션마다 1,000줄짜리 README를 붙여넣고 있다면, 그 이점은 상당할 것입니다. 이미 집중된 컨텍스트(context)를 사용하고 있다면 이점은 더 작겠지만, 주로 중복된 재설명을 피할 수 있다는 점에서 실질적인 효과가 있습니다.

방해가 되지 않는 구현 (Implementation)

설치는 간단합니다:

git clone https://github.com/OoneBreath/claude-code-project-brain.git
cd claude-code-project-brain
./install.sh

설치 후 새로운 Claude Code 세션을 시작하세요 (기술은 세션 시작 시 로드됩니다). 그런 다음 워크스페이스(workspace) 내부에서 해당 기술을 호출하고 무엇을 할지 지시하세요:

/project-brain   →   "init"은 브레인(brain)을 설정하고 프로젝트를 감지합니다

이 시스템은 의도적으로 가볍게 설계되었습니다:

• package.json / pyproject.toml / git을 통해 프로젝트를 감지합니다.
• 코드베이스(codebase)를 미리 스캔하지 않습니다 (명시적으로 백필(backfill)하지 않는 한).
• 직접 편집할 수 있는 일반 마크다운(markdown) 파일을 생성합니다.

트레이드오프 (The Tradeoffs)

이것은 마법이 아닙니다. 지식 관리(knowledge management)에 대한 절제된 접근 방식입니다:

1. 점진적 구축 (Gradual buildup): 한 번에 방대한 양을 쏟아붓는 것이 아니라, 작업하면서 브레인이 채워집니다.
2. 문서의 진실성 (Truth in documentation): 사용자가 명시적으로 기록하거나 백필(backfill)한 내용만 알고 있습니다.
3. 가벼운 유지보수 (Light upkeep): 원할 때 사용할 수 있는 번들형 브레인 체크 검증기(brain-check validator)가 포함되어 있습니다. 큰 변경 사항이 있을 때 실행하여 끊어진 링크나 상태 드리프트(status drift)를 잡아내세요. 이는 선택 사항이며 의무적인 작업이 아닙니다.

다른 방식이 실패할 때 이 방식이 작동하는 이유

대부분의 "AI 메모리" 솔루션은 다음 두 가지 실수 중 하나를 범합니다:

1. 데이터베이스의 오류 (The Database Fallacy): 모든 것을 벡터 스토어(vector store)에 쏟아붓는 것이 문제를 해결할 것이라고 가정합니다 (그렇지 않습니다. 검색(retrieval)은 여전히 비용이 많이 들고 노이즈가 심합니다).
2. 플랫 파일의 함정 (The Flat File Trap): 탐색이 불가능할 정도로 계속 커지는 notes.md 파일을 만듭니다.

Project Brain이 작동하는 이유는 인간 엔지니어가 실제로 시스템을 생각하는 방식을 반영하기 때문입니다:

• 상위 수준의 지도(high-level map)에서 시작합니다.
• 필요할 때만 세부 사항으로 파고듭니다.
• 현재 상태뿐만 아니라 결정 이력(decision history)을 보존합니다.

과도한 몰입 없이 시작하기

실용적인 접근 방식:

1. 스킬(skill) 설치
2. 활성화된 프로젝트 하나에서 초기화(init) 실행
3. 평소처럼 작업 - 브레인(brain)이 유기적으로 구축되도록 두기
4. 명확한 필요성이 느껴질 때만 소급 적용(backfill)

일주일이 지나면 다음과 같은 차이를 느끼게 될 것입니다:

• 세션 설정 시간
• 프로젝트 간 명확성 (Cross-project clarity)
• "잠깐, 우리 이거 이미 해봤는데"라고 말하는 순간의 감소

이 시스템의 진정한 힘은 시간이 흐르면서 나타납니다. 브레인이 단순히 무엇을 만들었는지뿐만 아니라, 왜 그런 방식으로 만들었는지까지 축적하기 때문입니다. 이것은 보통 근속 연수가 긴 팀에만 존재하는 조직적 기억(institutional memory)의 일종입니다. 이제 당신의 AI 어시스턴트도 이를 갖게 되었습니다.