저는 동시에 여러 제품을 다룹니다. 그중 하나는 마이크로서비스(microservices), 인프라(infrastructure), 설정 레포지토리(config repo)를 포함하여 20개의 레포지토리로 구성되어 있습니다. 전형적인 작업은 3~4개의 레포지토리를 건드리게 되는데, 코딩 에이전트(coding agent)와 새로운 세션을 시작할 때마다 저는 항상 똑같은 루틴으로 시작했습니다. 어떤 서비스가 존재하는지, 누가 누구를 호출하는지, 설정(configs)은 어디에 있는지, 그리고 이 제품이 도대체 무엇을 하는지 설명하는 것이었죠. 세션이 끝나면 — 이 모든 것을 다시 설명해야 했습니다.

한동안 저는 임시 지침 파일(instruction files)로 버텼습니다. 작업이나 에픽(epic)마다 하나씩 작성하여 세션에서 세션으로 끌고 다녔습니다. 하지만 여러 사람이 동일한 에픽에서 작업할 때는 이 파일들도 세심하게 업데이트해야 했고, 새로운 작업을 할 때는 종종 여러 개의 오래된 지침을 한꺼번에 에이전트에게 입력하게 되었습니다. 작동은 했지만, 매우 번거로웠습니다.

다른 사람들은 이 문제를 어떻게 해결하는지 찾아보았지만, 확립된 접근 방식은 찾을 수 없었습니다. 모두가 각자 만든 방식을 사용하고 있었습니다. 어떤 이들은 레포지토리 절반에 CLAUDE.md 파일을 두어 조용히 방치하고 있었고, 어떤 이들은 기술(skills)과 MCP 설정을 10개의 프로젝트에 걸쳐 복사하여 붙여넣고 있었습니다. 메모와 임시 파일들은 사방에 흩어져 있었습니다. 여러 레포지토리와 제품에 걸쳐 에이전트 컨텍스트(agent context)를 정리하는 표준이 전혀 없었습니다.

그래서 저는 저만의 방식을 만들었고, 이를 오픈 템플릿으로 패키징했습니다: agent-workspace. 아래는 이것이 어떻게 작동하는지, 왜 작동하는지, 그리고 동료들에게 보여주었을 때 받았던 질문들에 대한 답변입니다.

아이디어

하나의 디렉토리 — 에이전트를 위한 단일 진입점(single entry point). 당신이 다루는 모든 조직, 제품, 레포지토리가 그 안에 존재합니다. 에이전트는 항상 루트(root)에서 시작합니다.

컨텍스트는 계층적으로 구축됩니다 — 4단계의 CLAUDE.md 파일, 4단계의 추상화(abstraction) 수준입니다:

• Workspace (워크스페이스) — 특정 회사에 종속되지 않은 에이전트 행동의 기본 규칙 (base rules).
• Organization (조직) — 비즈니스가 무엇인지, 무엇이 중요한지(스타트업과 대기업은 우선순위가 다름)에 대한 간략한 설명과 커밋 스타일, 공유 인프라와 같은 회사의 관례 (conventions). 개인 프로젝트도 하나의 "조직"으로 간주됩니다.
• Product (제품) — 제품이 무엇인지, 어떤 리포지토리 (repositories)로 구성되어 있는지, 그리고 이들이 서로 어떻게 연관되어 있는지에 대한 내용.
• Repository (리포지토리) — 구조, 빌드 (build), 실행 (run), 주의사항 (gotchas)과 같은 저수준 (low-level) 세부 사항. 이 파일은 리포지토리 내부에 존재하며 리포지토리와 함께 이동합니다.

한 가지 핵심 규칙이 있습니다: 모든 사실은 정확히 하나의 계층에만 존재해야 합니다. 마이크로서비스 (microservices)가 어떻게 연결되어 있는지는 제품 (product) 레벨에, 빌드 명령 (build command)은 리포지토리 (repo) 레벨에 위치합니다. 아무것도 중복되지 않으므로, 두 곳에서 동시에 정보가 오래되어(stale) 발생하는 문제가 없습니다.

로컬 포트 (local ports), 개인 개발 토큰 (personal dev tokens)과 같이 머신에 특화된 모든 사항은 CLAUDE.local.md에 들어갑니다. 이 파일은 해당 리포지토리의 CLAUDE.md 옆에 리포지토리 레벨에서만 생성됩니다. 공유 파일은 보통 팀에 의해 유지 관리되는 반면, 로컬 파일은 그 위에 얹혀진 개인적인 세부 사항 계층이며 git에 커밋되지 않습니다.

계층 외에도, 루트 (root)에는 헬퍼 디렉토리 (helper directories)와 모든 기술 (skills), 명령 (commands), 에이전트 (agents)를 담은 단일 .claude가 포함되어 있으며, 이들은 루트 하위의 모든 곳에서 작동합니다. 기본 구조는 다음과 같습니다:

agent-workspace/
├── CLAUDE.md            # 워크스페이스 레벨: 기본 에이전트 규칙
├── .claude/             # 기술, 명령, 에이전트 — 모든 것을 위한 하나의 세트
...

실제 작업에서의 모습

하나의 제품을 예로 들어보겠습니다. 이름을 Hamsterflow라고 부릅시다. 여기서 하나의 작업이 8개의 리포지토리 중 3개의 마이크로서비스 (microservices)를 건드리는 상황입니다. 에이전트는 워크스페이스 루트 (workspace root)에서 시작하여 다음과 같이 동작합니다:

1. 루트 CLAUDE.md를 읽습니다 — 동작 규칙 (behavior rules).
2. 조직 (organization) 디렉토리로 내려가 해당 CLAUDE.md를 읽습니다 — 회사 컨텍스트 (company context) 및 컨벤션 (conventions).
3. 제품 (product) 디렉토리로 들어가 제품 CLAUDE.md를 읽습니다 — 이제 에이전트는 제품의 모든 리포지토리 (repositories)와 그 연결 방식을 알게 되며, 작업이 어떤 세 가지 리포지토리를 건드릴지 이해합니다.
4. 해당 세 개의 리포지토리에 진입하여 각각의 CLAUDE.md 파일들을 읽습니다.

그게 전부입니다. 에이전트는 인접한 다른 제품들을 스캔하지 않았고, 제 노트나 개인 리포지토리에도 손을 대지 않았습니다 — 이 모든 것들이 동일한 디렉토리에 있음에도 불구하고 말이죠. 에이전트는 오직 작업 경로를 따라 연결된 체인 (chain)만을 읽었습니다.

이 체인은 제품에 대한 지식을 제공하지만, 작업 자체에 대한 지식은 제공하지 않습니다. 이를 위해 워크스페이스 (workspace)에는 전용 공간인 workflow/task/<ticket-number>/가 있습니다. 이곳에는 현재 상태, 완료된 사항, 진행 방향, 그리고 해당 작업을 위한 최신 문서 링크가 담긴 작업 파일 (working file)이 있습니다 (문서 자체는 동일한 디렉토리에 저장되며, Confluence에 있는 경우 링크만 포함됩니다). 세션이 시작될 때 저는 단순히 이 파일을 에이전트에게 전달합니다. 그러면 에이전트는 제품뿐만 아니라 우리가 어제 어디까지 진행했는지도 즉시 알게 됩니다.

이 모든 과정을 거친 후의 시작 컨텍스트 (starting context)는 약 27k 토큰 (system prompt, tools, MCP 제외) 정도이며, 에이전트는 제가 평소에 일일이 설명해야 했던 제품에 관한 모든 것을 이미 알고 있습니다. 비교를 하자면, 이러한 구조가 없을 때 동일한 세 개의 서비스에 대해 "여기서 일이 어떻게 돌아가는지 파악해봐"라고 시키면 60~120k 토큰을 소모합니다 — 에이전트가 즉시 프로젝트들을 심층적으로 스캔하기 시작하기 때문입니다. 하지만 이 구조를 사용하면 대부분의 내용이 이미 CLAUDE.md 파일들에 작성되어 있으며, 코드를 읽어야 할 때도 관련 파일들을 훨씬 더 빠르게 찾을 수 있습니다. 이미 읽어온 체인에 모듈 (modules)과 주요 클래스 (key classes)의 이름이 명시되어 있기 때문입니다. 그리고 이 과정은 단 한 번이 아니라 매 세션마다 반복됩니다.

솔직히 말해서 중요한 주의 사항이 하나 있습니다. 토큰(token) 측면에서 이것이 항상 이득인 것은 아닙니다. 무엇을 어디서 수정해야 하는지 정확히 알고 있을 때는, 특정 파일을 가리키는 좁은 범위의 프롬프트(prompt)가 그 어떤 구조보다 훨씬 더 많은 것을 절약해 줍니다. 이 경우 CLAUDE.md 체인을 읽을 이유가 전혀 없습니다. 이 방식의 이점은 프로젝트 간 작업(cross-project tasks)에서 나타납니다. 사물들이 어떻게 연결되어 있는지에 대한 전체적인 그림 없이는 아무것도 할 수 없는 상황에서 말이죠. 그리고 이 이점은 무엇보다도 개발 시간 측면에서 나타납니다. 에이전트가 첫 순간부터 상황을 파악하게 되며, 매일 똑같은 이야기를 반복할 필요가 없기 때문입니다.

부패 방지하기

에이전트를 위해 작성된 모든 문서의 주요 질병은 다음과 같습니다. 바로 조용히 쓸모없게(stale) 변한다는 것입니다. 템플릿은 두 가지 방식으로 이 문제를 다룹니다.

모든 CLAUDE.md에는 마지막 업데이트 날짜가 찍혀 있습니다. 그리고 두 가지 전용 스킬(skills)이 있습니다. 하나는 각 레벨에 대해 고정된 구조로 파일을 생성하는 것이고, 다른 하나는 기존 파일을 새로고침하는 것입니다. 새로고침 스킬은 날짜 스탬프를 가져와 해당 날짜 이후의 커밋(commit)과 코드(그리고 Jira/Confluence가 연결되어 있다면 회사의 문서까지)를 살펴보고, 오래된 내용은 삭제하며, 새로운 내용은 추가하고, 스탬프를 업데이트합니다. 별도의 스킬 없이 에이전트에게 "문서를 업데이트해줘"라고 요청할 수도 있지만, 스킬은 규칙을 엄격하게 정의합니다. 무엇을 진실의 원천(source of truth)으로 간주할지, 무엇이 어느 레벨에 들어갈지, 무엇을 아예 쓰지 말아야 할지 등을 말이죠. 이를 통해 업데이트는 쓰레기를 생성하고 반복될수록 품질이 저하되는 복권 같은 방식이 아니라, 예측 가능한 과정이 됩니다.

workspace-manager

템플릿에는 이 구조를 관리하는 에이전트가 포함되어 있습니다. /init_workspace_manager 명령어로 시작하면, 에이전트가 현재 무엇을 가지고 있는지 묻고 스스로 모든 것을 설정합니다. 조직(organizations)과 제품(products)을 생성하고, 로컬 경로 또는 GitHub/GitLab URL로부터 기존 리포지토리(repositories)를 통합합니다. 로컬 리포지토리의 경우 이동하는 대신 복사합니다. 이때 IDE 설정과 로컬 환경 파일(.env)도 함께 복사하므로, 모든 것을 확인하기 전까지 원본은 온전하게 유지되면서 복사본은 즉시 실행 가능한 상태가 됩니다.

각 저장소(repo)를 확인할 때마다 CLAUDE.md 파일이 존재하는지 체크하고, 이를 생성하거나 새로 고칠 것을 제안하며, 해당 저장소가 어떤 제품에 속하는지 결정(또는 질문)합니다. 이 모든 과정은 저녁 시간 한 번이면 충분합니다.

그 범위는 워크스페이스(workspace) 자체입니다. 즉, 구조를 설정하고, 저장소들을 통합하며, CLAUDE.md 파일과 설정을 최신 상태로 유지하는 것입니다. 실제 코딩 작업은 이 도구 없이 일반적인 세션에서 수행합니다.

팀 단위에서는 어떻게 하나요?

가장 흔한 질문은 이것입니다: "이건 독재 아닌가요? 팀 전체가 당신의 구조를 따라야만 하나요?" 아닙니다. 동기화는 세 가지 계층에서 작동합니다:

• 저장소 수준(Repository-level)의 CLAUDE.md — 공유됩니다. README처럼 저장소 자체에 존재하며, 팀에 의해 푸시(push)되고 유지 관리됩니다. 워크스페이스 사용 여부와 관계없이 모든 사람에게 적용됩니다.
• 워크스페이스, 조직 및 제품 수준 — 당신만의 개인적인 영역입니다. 동료는 자신만의 워크스페이스를 구축할 수도 있고 전혀 구축하지 않을 수도 있으며, 어느 쪽이든 당신에게 영향을 주지 않습니다.
• 기술, 명령, 에이전트 — .claude에 있는 모든 것 — 20개의 마이크로서비스(microservices)에 일일이 복사할 필요가 없습니다. 제품당 별도의 저장소를 생성하고, 이를 플러그인 마켓플레이스로 설정하면 됩니다. 이는 이러한 요소들을 공유하기 위한 Claude Code의 공식 메커니즘입니다. 모든 사람이 필요한 것을 가져다 쓰며, 업데이트는 단 하나의 명령어로 이루어집니다. 워크스페이스 루트(root)에서 활성화된 플러그인은 그 하위의 모든 제품에 적용됩니다.

컨텍스트(Context): 우려와 수치

"에이전트가 거대한 컨텍스트를 갖게 되어 결국 모든 것을 훑게 될 것이다." 실제로는 그렇지 않습니다. 읽기 작업은 작업 경로(task path)를 따르며, 나머지 트리 구조는 전혀 건드리지 않습니다. 또한 전체 트리를 훑는 인덱싱(indexing) 과정도 없습니다. Claude Code는 코드베이스의 인덱스를 아예 구축하지 않으며, 필요할 때마다 실시간으로 코드를 검색합니다.

루트(root)에 있는 스킬들은 컨텍스트를 부풀립니다. 그리고 또한 그렇지 않습니다. 각 스킬의 이름과 짧은 설명만 자동으로 컨텍스트에 들어갑니다. 전체 지침은 해당 스킬이 실제로 사용될 때만 로드됩니다. MCP 서버는 더 심각합니다. 모든 도구에 대한 설명을 담고 있어 총 20–30k 토큰을 쉽게 소모할 수 있습니다. 따라서 현재 작업에 필요하지 않은 것들은 한꺼번에 실행 상태로 두지 말고 꺼야 합니다.

대용량 컨텍스트에서의 컨텍스트 저하(Context degradation)는 기억할 가치가 있지만, 중요한 것은 그것이 어디에서 오는지입니다. 현대의 강력한 모델들은 순수한 양은 비교적 잘 처리합니다. 하지만 이들을 훨씬 더 괴롭히는 것은 주제적으로 파편화된 컨텍스트입니다. 즉, 서로 다른 주제와 작업들이 뒤섞여 있고 내용의 절반가량이 현재 작업과 아무 관련이 없는 경우입니다. 레이어드 리딩(Layered reading)은 바로 그것에 대해 보호합니다. 오직 작업 경로를 따라 이어지는 체인만 컨텍스트에 들어가고, 그 안의 모든 내용은 지금 당신이 작업하고 있는 것에 관한 것입니다.

보안 (Security)

당연한 이야기를 하겠지만 건너뛸 수 없습니다. 이런 방식으로 작업하면 모델은 당신의 제품에 대한 많은 것들—아키텍처, 서비스 관계, 코드—을 보게 됩니다. 저에게는 간단합니다. 기업 계정의 경우 회사에서 규칙을 설정했기 때문에 고객 데이터가 모델에 절대 도달하지 않습니다. 이 부분이 귀사 측에서는 어떤지 확인해 보세요. 이동(move)하기 전에, 후에가 아니라요.

또 한 가지: 몇몇 회사와 당신의 개인 프로젝트들이 하나의 진입점(entry point)에 나란히 놓여 있을 때, 에이전트가 실수로 모델과 공유할 의도가 전혀 없었던 무언가를 가져갈 수 있습니다. 규칙에 맞지 않는 것은 작업 공간에 넣지 마세요.

그리고 기본적인 위생 관념: 비밀 정보는 어떤 레벨의 CLAUDE.md에도 속해서는 안 됩니다. 개인 개발 토큰은 .gitignore된 CLAUDE.local.md에 넣고, MCP 설정의 토큰은 환경 변수(environment variables)에서 가져와야 합니다.

Claude 결합 (About the Claude coupling)

이 파일들의 이름이 CLAUDE.md인 이유는 Claude Code가 기본적으로 이 파일들을 읽기 때문입니다. 저는 Claude Code에서 작업하고 있으며, 첫 번째 버전에서는 확실히 작동할 것이 보장되는 방식을 선택했습니다. 만약 여러분이 AGENTS.md 표준을 따르는 Cursor나 다른 도구를 사용 중이라면, workspace-manager는 첫 설정 과정에서 모든 파일의 이름을 변경하고 모든 언급을 다시 작성할 것을 제안할 것입니다. 솔직히 말씀드리면, 다른 에이전트들이 이 구조에서 어떻게 동작하는지는 아직 테스트해보지 않았습니다.

사용해보기

1. 템플릿을 클론(Clone)하고 Claude Code에서 엽니다.
2. /init_workspace_manager를 실행합니다. 그러면 설정 및 리포지토리(repositories) 통합 과정을 안내해 줄 것입니다.
3. 실제 콘텐츠가 준비되면 org_1/org_2 모의 스켈레톤(mock skeletons)을 삭제하세요 (에이전트가 삭제를 제안할 것입니다).

템플릿은 새로운 기술(skills), 명령어(commands), 에이전트(agents), 그리고 기존 기능의 개선사항과 함께 계속 진화할 것입니다. 이를 위해 workspace-update 기술이 있습니다. 이 기술은 여러분의 워크스페이스를 소스 리포지토리와 비교하며(워크스페이스에 기록된 템플릿 버전이 기준점이 됩니다), 변경된 내용을 보여준 뒤, 여러분의 확인을 거쳐 업데이트를 가져옵니다. 이때 여러분의 콘텐츠(조직, 제품 및 노트)는 건드리지 않고 그대로 유지됩니다.

다른 분들은 이 문제를 어떻게 해결하고 있는지 궁금합니다. 만약 에이전트를 위해 멀티 레포지토리(multi-repo) 컨텍스트를 다르게 구성하고 있다면 저에게 알려주세요.

By Vladislav, edited with Claude