r/ClaudeCode•7일 전•42•135

Claude Code 세션 간에 '결정 사항'(채팅 기록이 아닌)을 어떻게 유지하시나요?

How do you carry *decisions* (not chat history) across Claude Code sessions?

핵심 요약

Claude Code 세션 간에 휘발되는 의사결정 기록을 유지하기 위해 ADR, 문서화, 전용 워크플로우를 활용하는 다양한 방법이 논의되었습니다.

ADR 활용 — 아키텍처 결정 기록을 통해 의사결정 근거를 코드와 연동함
문서화 전략 — CLAUDE.md 및 별도 마크다운 파일을 통해 지식 베이스 구축
자동화 워크플로우 — 세션 종료 시 /documentation 명령으로 결정 사항을 아카이빙함
이슈 트래킹 — GitLab/GitHub 이슈를 활용해 사양과 결정 사항을 체계적으로 관리함

히스토리 보관 문제는 이제 거의 해결된 거나 다름없음. Claude Code는 세션 로그를 로컬에 저장하고, CLAUDE.md랑 AGENTS.md에는 상시 규칙이 박혀 있고, 코드는 Git이 관리하니까. 근데 나한테 여전히 골치 아픈 건 '의사결정의 상태'임. 이건 그냥 대화 내용이랑은 차원이 다른 문제거든.

내가 계속 겪는 5가지 상황은 이거임:

A를 시도했다가 X 때문에 깠는데, 새 세션에서 또 A를 제안함.
B가 승인됐는데, 조건부였음("이 모듈에만 적용", "마이그레이션 전까지만"). 근데 나중에 그 조건이 증발함.
구현은 했는데 배포는 안 된 상태인데, 다음 세션에선 그걸 이미 라이브 상태인 것처럼 취급함.
예전 에이전트가 "완료"라고 했는데, 까보니까 검증 과정이 말만 번지르르하고 부실했음.
나중에 내린 결정이 이전 결정의 일부를 대체했는데, 둘 다 여전히 유효한 것처럼 적혀 있음.

너희는 이런 거 어떻게 처리함? CLAUDE.md, AGENTS.md, ADR, decisions.md, git notes, native memory, gptme, 직접 짠 스크립트, 아니면 그냥 깡으로 버티는 중? 만약 이런 문제가 아예 안 생기거나, 그냥 파일 몇 개로 잘 관리하고 있다면 그것도 좋은 답변임. "우리는 X를 쓰는데, Y에서 자꾸 막힌다" 식으로 짧게 알려주면 딱 좋음.

참고로 나 이 문제 파고드는 프로젝트(Delimit) 하고 있음. 링크는 안 남김. 그냥 다들 실제로 어떻게 해결하고 있는지 궁금해서 물어보는 거임.

원문

커뮤니티 목록

r/ClaudeCode•7일 전•42•135

Claude Code 세션 간에 '결정 사항'(채팅 기록이 아닌)을 어떻게 유지하시나요?

How do you carry *decisions* (not chat history) across Claude Code sessions?

핵심 요약

Claude Code 세션 간에 휘발되는 의사결정 기록을 유지하기 위해 ADR, 문서화, 전용 워크플로우를 활용하는 다양한 방법이 논의되었습니다.

ADR 활용 — 아키텍처 결정 기록을 통해 의사결정 근거를 코드와 연동함
문서화 전략 — CLAUDE.md 및 별도 마크다운 파일을 통해 지식 베이스 구축
자동화 워크플로우 — 세션 종료 시 /documentation 명령으로 결정 사항을 아카이빙함
이슈 트래킹 — GitLab/GitHub 이슈를 활용해 사양과 결정 사항을 체계적으로 관리함

내가 계속 겪는 5가지 상황은 이거임:

A를 시도했다가 X 때문에 깠는데, 새 세션에서 또 A를 제안함.
B가 승인됐는데, 조건부였음("이 모듈에만 적용", "마이그레이션 전까지만"). 근데 나중에 그 조건이 증발함.
구현은 했는데 배포는 안 된 상태인데, 다음 세션에선 그걸 이미 라이브 상태인 것처럼 취급함.
예전 에이전트가 "완료"라고 했는데, 까보니까 검증 과정이 말만 번지르르하고 부실했음.
나중에 내린 결정이 이전 결정의 일부를 대체했는데, 둘 다 여전히 유효한 것처럼 적혀 있음.

참고로 나 이 문제 파고드는 프로젝트(Delimit) 하고 있음. 링크는 안 남김. 그냥 다들 실제로 어떻게 해결하고 있는지 궁금해서 물어보는 거임.

주요 댓글

r/claudecode

대부분의 사용자는 ADR(아키텍처 결정 기록)과 마크다운 문서를 활용해 의사결정 맥락을 유지하고 있으며, 일부는 커스텀 명령어나 이슈 트래킹 시스템을 통해 세션 간 지식 단절을 해결하고 있습니다.

아키텍처 결정 기록(ADR)을 사용함.

솔직히 ADR 없이 적당한 규모 이상의 레포지토리에서 LLM과 에이전트로 개발하는 사람들을 어떻게 하는 건지 모르겠음.

ADR은 사양으로 이어지고 사양에서 참조됨. 에이전트는 결국 코드 곳곳에 참조를 남기게 됨. 즉, 다음에 함수를 수정하는 에이전트는 참조된 ADR을 다시 확인하고 그 근거를 볼 수 있다는 뜻임.

또한 '왜'라고 물어보면 '사실 그 방식으로 구현하려고 명시적으로 검토했지만...' 같은 답변을 들을 수 있음.

코드에서 ADR을 링크하는 게 '왜'라는 질문에 대한 가장 강력한 답변인 것 같네. 어디서 어려움을 겪음? 이전 ADR의 조항 하나를 대체하는 ADR 같은 경우 말이야. '대체됨(superseded-by)' 표시를 해두면 에이전트가 실제로 그걸 존중함?

AGENTS.md에 ADR이 어떻게 작동하는지(대체, 번호 매기기, 권위 등) 설명하거나 같은 내용을 설명하는 다른 파일을 참조하게 함.

ADR이 다른 ADR로 완전히 대체되는 경우라면 그냥 완전히 대체하는 게 더 쉽다는 걸 알게 됐음. 작은 조항만 바뀌는 거라면 인라인으로 처리하거나, 바뀐 동작을 다루는 새로운 작은 ADR을 만들어서 참조하는 게 나음.

이게 최선의 방법인지는 모르겠지만, 잘 작동하는 것 같음.

나도 나만의 SDLC 스킬과 워크플로우를 만들면서 ADR을 사용 중임. 아직 이걸로 많은 걸 만들진 않았고 계속 다듬는 중이라 참고만 하길 바람...

내 생각에 코드가 ADR을 직접 인용해서는 안 된다고 봄. ADR 하나가 수많은 구현을 이끌어낼 수 있는데, ADR을 대체할 때마다 코드 주석을 다 바꾸는 건 얻는 거에 비해 노력이 너무 많이 듦.

내 워크플로우는 기능마다 사양과 수락 기준(AC)이 있는 방식임. 기능이 ADR을 도입할 수 있고, AC가 ADR을 그 이유로 인용할 수 있음. 내 워크플로우에서 AC는 비어 있거나 ADR을 가리키는 '결정자(decided-by)' 필드를 가짐. 각 AC는 고유 ID를 갖고 모든 AC는 테스트 코드에서 인용됨.

새 ADR이 기존 ADR을 대체하면 AC를 폐기하거나 업데이트하게 되는데, 이게 코드 변경을 유도함. 새 ADR이 기존 AC에 영향을 주지 않는다면 코드 내 ADR 인용을 업데이트하려고 굳이 변경할 필요는 없음.

코드 인용은 검증 방식으로서도 매우 취약함. 에이전트가 문서에 낡은 참조를 남겨두기 너무 쉽거든. 나도 테스트 코드에 인용된 AC에서 같은 결함을 겪지만, 테스트 도메인을 인용 소스로 선택한 이유는 언어의 타입 시스템이나 텔레메트리를 활용해서 프로덕션 코드에 영향을 주지 않고도 누락된 인용을 추적할 수 있기 때문임.

이 모든 걸 고려해도 좋은 ADR을 작성하는 건 정말 힘든 싸움임. 종료 계약을 약속하는 ADR 하나가 잘못 들어가면 다음 기능에서 단위 테스트 대신 기능 빌드 바이너리 테스트를 하려고 들 거임. ADR에 '환경 변수는 메인 진입점에서만 읽을 수 있음'이라고 적혀 있으면, 프로젝트 전체의 파이썬 임포트를 확인하는 '표면적' 단위 테스트 파일이 생기거나, 언어 파서를 사용해 임포트 문을 검증하는 단위 테스트가 생길 수도 있음. 프로그램이 작은 장난감 수준이라면 REPL 프로그램이라는 ADR을 작성하고 싶어 할 거고, 나중엔 REPL이 아닌 진입점을 추가하려는 너랑 싸울 거임. '언어 표준 라이브러리만 사용'이라는 ADR을 허용했나? 이제 설정 파일에 encoding/json만 쓰려고 할 거임.

결론적으로 내 경험상 ADR은 효과적임. LLM이 ADR을 어기는 걸 정말 싫어하거든. 하지만 ADR 작성을 대충 하지 마. 지금 좋아 보여도 나중엔 골치 아픈 싸움이 될 거임.

철저한 ADR을 유지하면서 가장 마음에 드는 점은 Claude가 계획이나 빌드 중에 ADR을 참조하고 우리가 방향을 바꿀 때임.

게다가 architecture.md와 매일 우리가 뭘 했는지 적는 활동 일지도 있음(git 커밋에 자세한 내용이 다 들어있긴 하지만). Claude에게 어딘가에 결정을 기록하라고 했을 때 ADR을 제안했는데, 난 그때까지 ADR을 들어본 적도 없었지만 아주 잘 작동함.

Claude가 스스로 ADR을 제안했다니 흥미롭네. 혹시 activities journal이 ADR이랑 충돌하는 경우는 없어? 예를 들어, journal에는 배포됐다고 나오는데 ADR에서는 대체됐다고 하는 경우 말이야. Claude는 둘 중 뭘 더 신뢰해?

나도 이런 방향으로 해킹하듯 해결해오고 있었는데, 혹시 공개된 스킬이나 모듈 같은 게 있음?

나는 팀별로 라운드 로그를 하나씩 유지하는데, 라운드당 한 줄씩 적어. 이런 이름이 있는 줄은 몰랐네.

CLAUDE.MD에 링크된 여러 MD 파일을 사용해서 항목을 찾아보게 함.

그 설정으로 5번 문제는 어떻게 처리해? 최신 MD 파일이 이전 파일의 일부를 덮어쓰는 경우 말이야. 이전 파일을 수정해, 아니면 둘 다 놔두고 에이전트가 알아서 조정하게 해?

덧붙이자면... 요구사항 문서, 구현 계획, 계약, SQL DDL 등과 함께 ADR에도 크게 의존함. 사실 요구사항 문서 다음으로 ADR이 프로젝트에서 가장 중요한 정보라고 생각함. 이런 것들을 가능한 한 잘게 나누고(적당한 선에서), 구현 중인 기능에 필요한 것만 로드하는 것도 중요함.

주기적으로 리뷰 팀을 돌려서 낡은 문서가 없는지 확인하고, 더 이상 관련은 없지만 어딘가 안전하게 보관할 가치가 있는 문서는 아카이브함.

내가 이상한 건지 아니면 그냥 미친 건지 모르겠지만, 난 이렇게 함:

로컬에 GitLab을 설치해서 사용함(GitHub으로도 가능할 거라 생각함).

예를 들어 '모듈 Y에서 X를 해야 함' 같은 이슈를 만들고, 해야 할 일에 대한 기본적인 설명을 추가함. 그다음 이슈를 '정리(groom)'함. Claude가 코드를 보면서 세부 사항을 구체화함. 질문이 있으면 설명에 '열린 질문' 섹션을 추가하고 이슈를 '차단됨(blocked)'으로 표시함. 내가 구현할 때쯤이면 에이전트가 바로 가져다 쓸 수 있는 완벽한 사양이 되어 있음. 구현 중에 발견되는 건 뭐든 새로운 이슈로 만듦. 반복.

모든 결정은 이슈에 대한 댓글로 작성되고, Claude는 이슈 간의 관계를 파악하는 능력이 뛰어나서 모든 결정이 맥락을 가짐.

GitLab과 통신하는 MCP를 만드는 데 한 달 정도 걸렸음. Claude가 기본적으로 GitLab API와 대화할 수 있지만, 내가 만든 MCP는 내가 원하는 개발 라이프사이클을 강제함.

Obsidian 볼트, 프로젝트 계획 .md 파일, 위키 링크, 그리고 가장 중요한 날짜가 찍힌 ADR들.

원문r/ClaudeCode