CLAUDE.md와 함께 TODO.md 및 AUDIT_LOG.md를 도입하세요. 감사 로그 (Audit log)는 반복되는 오류를 획기적으로 줄여주며, 할 일 목록 (Todo)은 Claude Code가 여러분의 로드맵과 일치하도록 유지해 줍니다.

핵심 요약 (Key Takeaways)

• CLAUDE.md와 함께 TODO.md 및 AUDIT_LOG.md를 도입하세요.
• 감사 로그 (Audit log)는 반복되는 오류를 획기적으로 줄여주며, 할 일 목록 (Todo)은 Claude Code가 여러분의 로드맵과 일치하도록 유지해 줍니다.

CLAUDE.md를 넘어: Claude Code를 궤도에 유지시키는 2가지 파일

여러분은 프로젝트 규칙, 코딩 컨벤션 (Coding conventions) 등 CLAUDE.md 설정을 완벽하게 마쳤을 것입니다. 하지만 r/ClaudeAI의 한 개발자는 한 달간 매일 사용해 본 결과, 두 개의 추가 파일이 그 어떤 설정 변경보다 더 큰 차이를 만든다는 것을 발견했습니다. 그들이 찾아낸 내용과 여러분이 적용할 수 있는 방법을 소개합니다.

기술적 방법: TODO.md + AUDIT_LOG.md

개발자 u/annasfbi는 CLAUDE.md와 함께 두 개의 지속적인 프로젝트 파일을 유지합니다:

• TODO.md — 아이디어, 계획된 기능, 향후 작업에 대한 실행 목록.
• AUDIT_LOG.md — 실수, 그 원인, 수정 사항 및 방지 전략을 기록하는 개발 로그 (Development log).

그게 전부입니다. 화려한 도구는 필요 없습니다. 그저 Claude Code가 읽고 업데이트하는 일반적인 마크다운 (Markdown) 파일일 뿐입니다.

작동 원리

Claude Code의 컨텍스트 윈도우 (Context window) (Opus 4.6 기준 최대 1M 토큰)는 많은 정보를 담을 수 있음을 의미하지만, 세션 사이에는 내용을 잊어버립니다. 이 파일들은 CLAUDE.md 외부에 지속적인 메모리 (Persistent memory)를 제공합니다.

• TODO.md는 Claude Code가 프로젝트의 방향성과 일치하도록 유지합니다. 새로운 작업을 시작할 때 Claude는 TODO를 읽고 그에 따라 우선순위를 정합니다. 따라서 더 이상 "다음에 무엇을 해야 하나요?"라고 묻거나 경로를 이탈하는 일이 발생하지 않습니다.
• AUDIT_LOG.md는 진정한 게임 체인저입니다. 무엇이 잘못되었고 어떻게 수정했는지를 기록함으로써, Claude가 동일한 함정에 빠지지 않도록 가르치는 것입니다. 해당 개발자는 이것이 "동일한 오류가 다시 발생하는 것을 줄여주었다"라고 말합니다. 이는 디버깅 사이클의 감소, 토큰 소모(Token burn) 감소, 그리고 더 빠른 배포(Shipping)를 의미합니다.

이 방식이 작동하는 이유는 Claude Code가 이 파일들을 참조 자료(Reference material)로 취급하기 때문입니다. 유사한 문제에 직면했을 때, Claude는 감사 로그(Audit log)를 검색하여 패턴을 찾아내고 이미 알려진 해결책을 적용합니다. 이는 에이전트에게 사후 분석(Post-mortem) 라이브러리를 제공하는 것과 같습니다.

적용 방법

1. 프로젝트 루트에 파일 생성:

   touch TODO.md AUDIT_LOG.md

2. 현재 백로그(Backlog)로 TODO.md 채우기. 구체적으로 작성하세요:

   # TODO
   - [ ] OAuth2 로그인 흐름 구현 (우선순위: 높음)
   - [ ] 성능 향상을 위한 데이터베이스 쿼리 리팩터링 (Refactor)
...

3. 기억나는 과거의 실수들로 AUDIT_LOG.md 시작하기:

   # Audit Log
   ## 2026-08-02: 인증 과정에서의 레이스 컨디션 (Race condition)
   - 원인: 비동기 핸들러(Async handler)에서 await 누락
...

4. CLAUDE.md에서 Claude에게 이 파일들을 사용하도록 지시하기:

   세션 시작 시 항상 TODO.md와 AUDIT_LOG.md를 읽으세요. 작업이 완료되면 TODO.md를 업데이트하세요. 발생한 모든 오류는 원인, 해결책, 예방책과 함께 AUDIT_LOG.md에 기록하세요.

5. 지속적으로 업데이트하기 — 수동으로 하거나 Claude에게 요청하세요. 개발자는 때때로 두 파일 모두 수동으로 업데이트하지만, Claude에게 요청하면 자동으로 수행하기도 합니다.

기대 효과

• 반복되는 오류 감소 — Claude는 단순히 학습 데이터뿐만 아니라 사용자의 이력을 통해 학습합니다.
• 더 나은 방향성 — Claude는 무엇이 계획되어 있고 무엇이 완료되었는지 알게 되어, 업무 이탈을 줄입니다.
• 원활한 인수인계 — 브랜치를 전환하거나 기기를 변경하더라도, 이 파일들이 컨텍스트(Context)를 유지해 줍니다.

이 두 파일로 시작해 보세요. 비용이 들지 않고, 간단하며, 즉시 실행 가능합니다. 미래의 당신(그리고 당신의 토큰 예산)이 고마워할 것입니다.

출처: reddit.com

원문 게시지: gentic.news