Claude 코드 성능 10배 향상하는 .agent 폴더 기반 클라우드코드 문서화 시스템 실전 사례
클라우드코드(Cloud Code)를 활용하면서 프로젝트가 확장될수록 코드베이스가 점점 복잡해지고, 그에 따라 에이전트의 작업 효율이 떨어지는 문제를 자주 경험하게 됩니다. 에이전트의 컨텍스트(문맥) 관리를 체계적으로 최적화하는 '컨텍스트 엔지니어링'에 대해 실제 경험과 구체적인 운영 사례 중심으로 설명하겠습니다.
클라우드코드의 컨텍스트 한계와 구조 분석
클라우드코드 에이전트는 기본적으로 20만 토큰의 컨텍스트 제한을 가지고 있습니다. /contacts 명령으로 현재 토큰 사용 현황을 확인할 수 있는데, 전체 컨텍스트는 시스템 프라미스, 툴, 사용자 정의 에이전트, 메모리 파일(주로 cloud.md), 메시지 기록 등으로 구성됩니다.
시스템 프라미스와 기본 툴은 변경 불가하지만, 불필요한 사용자 정의 툴(MCPs)이나 안쓰는 커스텀 에이전트 파일을 제거하면 즉시 2% 이상의 컨텍스트 창을 확보할 수 있습니다.
특히 프로젝트가 커질수록 cloud.md 파일이 지나치게 커져서 실제 대화에 쓸 공간이 좁아지는 일이 자주 발생합니다. 이럴 때 사용하지 않는 에이전트 구성요소를 과감하게 정리하는 것만으로도 효율적인 컨텍스트 활용이 가능합니다.
컨텍스트 노이즈 줄이는 방법: 서브 에이전트와 컴팩트 명령 활용
에이전트에게 "구글 OAuth 추가 도움 요청" 같은 기능 작업을 지시할 경우, 실제 구현에 앞서 다양한 조사/리서치 단계에서 많은 토큰이 소모됩니다. 이런 경우 서브 에이전트 기능을 활용해 조사 단계의 토큰 소비를 별도 스레드에서 처리하고, 메인 대화엔 요약본만 남기는 방식이 효과적입니다.
예를 들어, 대규모 기능 구현 전 "리서치는 task 혹은 sub agent로 분리"하겠다는 문구를 사전에 추가하면 서브 에이전트의 추상적 연구 과정이 따로 분리되어 메인 컨텍스트의 노이즈를 대폭 줄일 수 있습니다.
또, 구현 분기마다 compact 명령을 적용해 이미 완료된 대화 기록을 정리함으로써 컨텍스트를 적극적으로 청소하면 남은 토큰을 더 생산적인 작업에 쓸 수 있습니다.
프로젝트별 맞춤 문서화 시스템: .agent 폴더 구조 및 운영
클라우드코드 최적화를 위해 실제 프로젝트에서 가장 널리 쓰이는 문서화 시스템이 .agent 폴더 기반 관리 방식입니다. 이 폴더 내에 task·system·SOP·readme md 파일을 생성/유지하는 방식을 소개하겠습니다.
task 폴더에는 각 기능별 PRD(기획문서)나 구현 계획을 저장합니다. 새 기능 구현 전 에이전트에게 plan mode를 요청해 상세 계획을 만들고 이를 task 폴더에 보관, 다음 유사 작업 때 레퍼런스로 재활용합니다.
system 폴더에는 전체 프로젝트 구조, DB 스키마, API 정의, 복잡한 코드파트 등, 에이전트가 전반적 구조를 파악하는 데 필요한 정보를 통합 제공합니다.
SOP 폴더에는 표준 작업 절차서나 에이전트가 이전에 실수한 경험을 바탕으로 수정한 작업 흐름을 저장합니다. 데이터베이스 테이블 추가/모델 연동 등 반복 작업이 많은 분야에 특히 유용합니다.
readme.md는 구조적으로 각 문서 파일의 인덱스 역할을 하여 에이전트가 어떤 정보를 어디에서 찾아야 할지 한 눈에 알 수 있게 만듭니다.
readme에서 의사결정 히스토리를 담아 복잡한 프로젝트에서도 정보 탐색이 쉬워집니다. 이 문서 시스템을 제대로 유지하면 에이전트가 코드를 전체적으로 요약한 스냅샷만 참고해 충분한 기본 정보로 곧바로 작업을 시작할 수 있습니다.
실제 운영 경험과 팀 사례
실제 AI Builder Club의 Simon 팀은 .agent 폴더 기반으로 Lexi 코드베이스 문서화 시스템을 구축했습니다. 방법은 아래와 같습니다.
먼저, 각 클래스의 인라인 문서를 최적화한 뒤, LLM 프롬프트로 상세 문서를 자동 생성하는 구조를 사용합니다. 이 방식은 초기엔 Claude에게 MD 파일 생성을 맡긴 뒤, 점진적으로 커서(cursor)·slash 명령 활용으로 발전시켰으며, 실무에서는 "클래스 리뷰 및 인라인 문서 갱신 → 상세 문서 추가"의 반복적 워크플로우로 프로젝트의 문서 품질을 체계적으로 관리합니다.
문서화 플로우 실전 예시
새 프로젝트 시작 시 cloud.md 파일에 문서 구조를 명확히 설명하고, "새 기능 구현 후 무조건 agent 폴더 문서 갱신"과 "플랜 전에 먼저 readme 확인" 규칙을 명시합니다. 이후 update doc 명령을 통해 문서 업데이트 규칙을 에이전트에게 전달합니다.
예를 들어, "텍스트→이미지 생성앱 구현"을 기획하면 plan 모드로 계획을 세운 뒤, 구현 계획을 do agent/task 폴더에 저장하고 개발을 진행합니다.
모델 통합에 실패하거나 오류가 발생시 SOP 자동 생성 기능을 통해 "Replicate 모델 연동 표준 작업서" 문서가 갱신되고, 관련 문서 인덱스까지 readme에 즉시 반영됩니다.
다음번 텍스트→비디오 기능을 추가할 때는 "agent doc 참고→plan 모드 실행"으로 에이전트가 기존 문서를 미리 검토해 필요한 정보만 효율적으로 활용합니다. 이렇게 반복적으로 update doc 및 compact 명령을 유지하면 각 기능별 구현 계획, 구조, 오류 대응 프로세스, 문서 히스토리까지 체계적으로 관리해나갈 수 있습니다.
특정 대화만 정리해도 이전 작업 흐름/의사결정 맥락이 readme 중심으로 남아, 언제나 안정적으로 확장/참고/재사용이 가능해집니다.
이 외에도 기존 코드베이스에 대해 시스템 아키텍처 문서, DB 및 API 정의, 중요 구조 파일을 생성하도록 클라우드코드 기능을 확장해 적용할 수 있습니다.
제안 및 세션 안내
AI Builder Club 등에서 자세한 실전 입문 세션·문서 예시, 명령어 템플릿 워크숍도 제공하고 있으니 관심 시 참고할 수 있습니다.
클라우드코드를 효과적으로 쓰려면, .agent 폴더 기반 구조화와 주기적 문서 갱신(계획/실수/SOP/레퍼런스)을 에이전트와 함께 유지한다는 점이 가장 실질적으로 성능을 높이고 프로젝트 완성도를 높입니다. 이 방식은 코드를 다루는 사람뿐만 아니라, 자동화 작업, 생산성 도구 연동, 업무운영 전반에도 확장 가능성이 크기에 적극적으로 시도해볼 만합니다.
클라우드코드 문서화와 컨텍스트 최적화를 고민한다면 실제 프로젝트와 경험담, 구체 사례를 참고해서 자신만의 체계적인 구조를 만들어보는 것이 좋겠습니다.
출처 및 참고 :
이 노트는 요약·비평·학습 목적으로 작성되었습니다. 저작권 문의가 있으시면 에서 알려주세요.