path
Jin's Lab
코드로 실험하고 기록하는 개발 일지 · J.Lab

Jin's Lab

코드로 실험하고 기록하는 개발 일지. 커리어와 삶의 방향을 탐색하며 기록하는 공간입니다

ai-workflow

Claude Code 서브에이전트 위임 사용량 줄이는 맥락 관리법

J.Lab ·
목차

    요즘 클로드 코드를 활용해 다양한 업무를 자동화하고 있다. 메인 세션 하나에서 요청을 보내면 작업 성격에 맞게 분류하여 전용 에이전트에게 전달하는 흐름을 만들고 싶었다.

    그래서 CLAUDE.md 파일에 '요청 접수·위임 규칙'을 새로 추가했다. GAS 디버깅, 테마 수정, 키워드 관리, 수익 전략, 워크로그 기록 등 5개 전용 에이전트를 지정하고 일을 나눠 맡기기 시작했다.

    위임 규칙 추가 후 발생한 사용량 폭발 문제

    시스템을 구축하고 나니 생각지도 못한 지점에서 막혔다. 에이전트들이 분깃을 받아 실행될 때마다 매번 사전 맥락이 없는 상태로 깨어났다.

    그러다 보니 에이전트가 단 한 줄의 수정 작업을 위해서도 용량이 큰 .gs 파일이나 테마 파일 전체를 통째로 뒤지기 일쑤였다. 메인 세션과 서브에이전트 간 대화가 늘어날수록 토큰 사용량이 그야말로 폭발적으로 치솟았다.

    메인 세션에서 서브에이전트로 업무가 위임되는 구조를 나타낸 아이소메트릭 일러스트

    단순히 역할을 분담한다고 해서 작업이 효율적이지 않았다. 에이전트가 매번 전체 프로젝트 파일을 읽지 않도록 읽기 범위를 제한하는 대책이 시급했다.

    .claude/자료지도.md 파일로 읽기 범위 고정하기

    삽질 끝에 내가 선택한 첫 번째 해결책은 읽어야 할 파일의 위치를 지정해 주는 것이었다. 업무별로 참조해야 하는 파일만 딱 집어주는 '.claude/자료지도.md' 문서를 새로 작성했다.

    그리고 5개의 서브에이전트가 첫 번째 단계에서 무조건 본인 전용 자료지도 항목만 읽고 작업을 시작하도록 연결했다.

    자료지도를 통해 에이전트의 읽기 범위를 제한하는 개념 일러스트

    이렇게 자료지도를 도입하자 에이전트가 소스코드 전체를 탐색하는 무의미한 탐색 과정이 사라졌다. 불필요한 파일 스캔이 줄어들면서 토큰 소모량도 크게 낮출 수 있었다.

    위임 지시 템플릿과 요약 스냅샷 구축

    파일 범위를 제한한 것 외에도 대화 맥락을 넘겨주는 방식 자체를 다듬었다. 메인 세션에서 서브에이전트로 넘길 때 구체적인 구조를 갖춘 '위임 지시 템플릿'을 적용했다.

    위임 지시문에는 '목표, 알게 된 것, 자료, 하지 말 것, 완료 기준'이라는 5가지 요소를 요약해서 넘겨주도록 규격화했다. 이렇게 하니 에이전트가 이전 대화 기록 전체를 파악할 필요 없이 핵심 목표에만 즉시 집중할 수 있었다.

    요약 템플릿과 스냅샷을 통해 작업 맥락을 전달하는 모습을 표현한 일러스트

    또한 기존 claude.ai 프로젝트에만 존재하던 색인 문제, GA4, 링크허브, 점검 로그 등의 자료가 걸림돌이었다. 이 자료들은 필요할 때마다 가져오기 어려워 요약 스냅샷으로 만들어 작업 폴더에 직접 복사해 두었다.

    Notion 실데이터로 카테고리 설정 정정하기

    위임 시스템을 정비하던 중 문서마다 IssueLog와 IT Story 카테고리가 서로 다르게 설정되어 있는 문제를 발견했다. 어떤 카테고리가 실제 노션에 반영되고 있는지 불명확해서 작동에 혼선이 생겼다.

    이 문제를 바로잡기 위해 노션의 실제 데이터를 직접 확인하는 작업을 진행했다. 데이터베이스 필드명을 점검한 뒤 올바른 값으로 CLAUDE.md 내 관련 규정을 정확하게 정정했다.

    결과적으로 잘못된 카테고리 분류로 인해 발생하던 위임 오류와 불필요한 다시 쓰기 작업을 깔끔하게 정리할 수 있었다.

    에이전트 팀 운영의 핵심은 맥락 전달 비용

    여러 AI 에이전트를 마치 하나의 팀처럼 나누어 돌려보면서 중요한 깨달음을 얻었다. 에이전트 다변화 과정에서 발생하는 진짜 비용은 모델 자체의 성능 차이가 아니라 '맥락 전달 비용'에 있었다.

    아무리 똑똑한 에이전트라도 매번 아무 맥락 없이 전체 코드를 읽게 만들면 사용량 부담을 감당하기 어렵다. 자료지도와 명확한 위임 템플릿, 그리고 정돈된 스냅샷을 적절히 배치하는 것만으로도 작업 속도와 효율을 비약적으로 끌어올릴 수 있었다.

    ai-workflow claude-code context-management prompt-engineering sub-agent
    ← 이전 글
    최근 게시물
    다음 글 →
    이전 게시물
    ≡ 글 목록으로
    소개
    path
    J.Lab

    커리어와 삶의 방향을 탐색하며
    기록하는 공간입니다

    카테고리
    403 Forbidden Error 1 429 Error 1 Ad Exchange 1 Ad Layout Guide 1 ad-slot 1 adsense 2 AdSense 2 AdSense Bot Detection 1 AdSense CTR 1 AdSense Display Issue 1 adsense-optimization 1 AI Automation 1 AI Image Generation 1 ai-automation 2 ai-book-writing 1 ai-image-generation 1 AI-Prompting 1 ai-side-hustle 1 ai-workflow 1 ai-writing 1 AIAutomation 1 AIBlogAutomation 1 AICodeLog 1 AIContentGeneration 1 AIImageGeneration 1 AIWritingErrors 1 API Automation 2 API Retry Design 1 api-automation 1 API-Deprecation 1 api-error 1 api-fallback 1 api-integration 2 api-pagination 1 api-retry-strategy 1 api-troubleshooting 1 APIDebugging 1 APIError 1 APIErrorHandling 1 APIIntegration 3 APIQuotaOptimization 1 APITokenRenewal 1 apps-script-trigger 1 AppsScript 1 appsScriptAutomation 1 AutomatedBlogging 1 automation 5 Automation 4 Automation Queue 1 Automation Scheduler 1 Automation Troubleshooting 1 automation-error 1 automation-script 1 AutomationBug 1 AutomationTroubleshooting 1 Backoff Algorithm 1 Base64 Image 1 Base64Encoding 1 batch-processing 1 BatchProcessing 1 Blog Optimization 2 blog-automation 4 blog-customization 2 blog-migration 4 blog-monetization 1 Blog-Sorting 1 blog-strategy 1 blog-theme-customization 1 blog-workflow 1 blogautomation 1 BlogAutomation 4 Blogger 13 Blogger API 2 Blogger Automation 2 Blogger SEO 1 blogger-api 4 blogger-automation 1 blogger-customization 1 blogger-error-400 1 blogger-labels 1 blogger-seo 1 blogger-theme 1 blogger-theme-debug 1 blogger-tips 1 Blogger-Tips 1 blogger-xml 1 BloggerAPI 7 BloggerAutomation 1 BloggerBypath 1 BloggerCustomization 2 BloggerFavicon 1 BloggerPermalink 1 BloggerTemplate 1 BloggerTemplateEditing 1 BloggerTheme 3 BloggerThemeCustomization 1 BloggerXMLStructure 1 Blogging-Automation 1 BloggingTools 1 BlogQuality 1 BlogSpot 1 Bug Fix 1 bug-fix 1 bug-hunting 1 BWidgetBIncludable 1 card-overlay-css 1 CardClickHandler 1 career-advice 1 CDATA 1 checklist-template 1 clamping-text 1 Claude 1 claude-ai 3 claude-code 2 ClaudeChat 1 ClaudeCode 1 CLIPTokenLimit 1 CloudflareWorkersAI 1 CNAME 1 Code Cleanup 1 Code Integration 1 code-refactoring 1 codelog 1 CodeLog 1 codeRefactoring 1 CodeStack 1 coding-log 2 comment-classification 1 config-pattern 1 Content Strategy 1 Content-Marketing 1 content-monetization 1 content-strategy 1 content-writing 1 contentsequencing 1 ContentStrategy 1 context-management 1 cost-reduction 1 CSS 1 css-axis-rotation 1 css-bug-fix 1 CSS-Debugging 1 css-fix 1 css-flexbox 1 css-layout 3 css-logo 1 css-print 1 css-troubleshooting 1 CSSLayout 1 CSSOverlay 1 Custom Domain 1 custom-theme 1 data-backfill 1 data-parsing 1 data-synchronization 1 data-validation 1 DatabaseDesign 1 DataMigration 1 DataRecovery 1 DataValidation 1 DateInjection 1 debugging 2 Debugging 5 Debugging Log 1 DebuggingLog 1 derived-state 1 detail-page-design 1 dev-journey 2 dev-log 1 Developer-Blog 1 developer-career 1 DeveloperJourney 2 DevJourney 1 DevLog 1 digital-creator 1 digital-products 2 display-none-seo 1 DOM-Inspection 1 dom-manipulation 1 Domain Migration 1 DomainMigration 1 DOMAutomation 1 duplicate-content 1 dynamic-menu 1 ebook-marketing 2 ebook-planning 1 ebook-publishing 5 editing-tips 1 Error Handling 2 error-handling 1 Error-Handling 1 ErrorHandling 2 EventDispatch 1 Execution Timeout 1 ExecutionLimit 1 exponential-backoff 1 FactChecking 1 FallbackSystem 1 FaviconEmbedding 1 Feed-API 1 filesystem 1 Flat Illustration 1 flux-model 1 FluxModel 1 FreeAIImage 1 frontend 1 Frontend 1 frontend-developer 1 frontend-layout 1 frontend-tips 1 FrontEndDev 1 FrontendTips 1 GAS 1 GAS Blogger API 1 GAS Refactoring 1 GAS Trigger 1 gas-automation 2 gas-optimization 1 gas-trigger 1 GASTimeout 1 gasTriggerManagement 1 GCP Project Linkage 1 Gemini 1 Gemini API 2 gemini-api 1 GeminiAPI 3 GeminiPrompt 1 GeminiPromptEngineering 1 getBoundingClientRect 1 github-raw-url 1 GmailRestrictions 1 Google AdSense 1 Google Apps Script 12 Google Discover 1 google-apps-script 8 Google-Apps-Script 1 google-blogger 1 googleAppsScript 1 GoogleAppsScript 12 googlesapps-script 1 GoogleSearchConsole 1 grep 1 hero-image 1 hero-image-validation 1 HTML Fix 1 HTMLCSS 1 HTMLWidgetBlogger 1 http-429 1 HuggingFace 1 HuggingFaceAPI 1 ico-generator 1 Image Optimization 1 image-automation 2 image-generation 1 image-hosting 1 image-optimization 1 image-processing 1 image-upload 1 ImageGeneration 2 ImageIntegrity 1 ImageOptimization 1 In-App Browser 1 invalid-argument 1 javascript 4 JavaScript 4 javascript-automation 1 javascript-toc 1 JavaScriptDevLog 1 JavaScriptInjection 1 jlab-codelog 1 JLabDevLog 1 json-schema 1 label-length-limit 1 lead-magnet 1 legacy-code 1 LinkedIn-API 2 LinkedIn-OAuth 1 LinkHub 1 linux 1 markdown 1 meta-description 1 MetaTags 1 Migration 1 Migration Script 1 mobile-friendly 1 Mobile-Web 1 monetization 1 Monitoring Automation 1 MultilingualSEO 1 NakedDomain 1 Negative Prompt 1 node-js 1 nodejs-automation 1 noindex-tag 1 Notion API 1 notion-api 3 notion-database 2 notion-gas-integration 1 notion-setup 1 notion-template 1 NotionAPI 3 NotionAutomation 1 notionintegration 1 NotionIntegration 1 OAuth Scope 1 OpenGraph 1 padding-overlap 1 pagination 1 payload-validation 1 pdf-generation 1 pdf-publishing 1 pdf-selling 1 permalink-management 1 PersonaDesign 1 pil-image-processing 1 Pinterest 2 PinterestAutomation 1 PipelineFix 1 playwright 1 Pollinations 1 Pollinations Flux 1 pollinations-ai 1 pollinations-api 2 PollinationsAI 1 PositionAbsolute 1 post-queue 1 productivity-tools 1 Prompt Design 1 Prompt Engineering 1 prompt-engineering 3 Prompt-Engineering 1 prompt-validation 1 PromptEngineering 3 Publishing Flow 1 publishorder 1 python-favicon 1 python-markdown 1 python-pil 2 python-scripting 1 Queue Design 1 queue-pattern 1 queue-stuck 1 RandomDelay 1 rate-limiting 1 react 1 React 1 Refactoring 1 Resource Exhausted 1 responsive-ads 1 responsive-design 4 ResponsiveCSS 1 ResponsiveDesign 1 retrospective 1 rfc3339 2 Robots Meta Tag 1 RSS Feed 1 rss-feed 1 RSSProxy 2 SAXParseException 1 Script Authorization 1 scriptNotFound 1 SDXL 1 Search Engine Optimization 2 Search-Engine-Optimization 1 SearchConsole 1 Self Rescheduling Trigger 1 SEO 2 SEO Tips 1 seo-optimization 5 SEO-Optimization 1 SEOOptimization 2 seriesmanagement 1 serverless-automation 1 sessionstart-hook 1 shell-script 1 Side Ad Duplication 1 side-income 1 side-project 1 SidebarLinks 1 SNSMarketing 1 Social-Media-Automation 2 SocialSharing 1 state-management 1 StaticWebPage 1 sub-agent 1 SVG Icon 1 svg-mask 1 SVGIcon 1 Synchronization 1 table-of-contents 1 tech-blogging 1 TechJournal 1 TechVibe 1 Template 1 TextSanitization 1 threads-api 2 Threads-API-Comparison 1 ThreadsAPI 3 time-driven-trigger 1 Tistory 2 tistory-customization 1 tistory-migration 1 tistory-skin 1 tistory-theming 1 tistory-tips 1 TOC Ad Placement 1 token-optimization 1 TranslationAPI 1 transparent-favicon 1 triggerCleanup 1 troubleshooting 2 Troubleshooting 2 typesetting 1 ui-optimization 1 unzip 1 URL Slug 1 UrlFetchApp 1 usememo 1 UTF8Encoding 1 vanilla-js 1 Web Development 2 Web Publishing 2 Web Security 1 web-development 7 Web-Development 2 web-development-log 1 web-development-tips 1 web-layout 1 Web-Layout 1 web-performance 1 web-publisher 1 web-scraping 1 WebAccessibility 1 WebAutomation 1 WebDebugging 1 WebDesign 2 WebDevelopment 10 WebDevelopmentTips 1 WebDevJourney 1 WebMigration 1 windows 1 windows-task-scheduler 2 WorkAutomation 1 workflow-automation 1 WorkflowAutomation 1 writing-process 1 XHTML 1 XMLCustomization 1 XMLParser 1 XMLSpecialCharacters 1 XMLTheme 1 z-index-issue 1 zip 1
    인기 글
    GAS에서 Blogger API 403 오류 완전 정복 — appsscript.json 스코프와 GCP 프로젝트 연결
    GAS에서 Blogger API 403 오류 완전 정복 — appsscript.json 스코프와 GCP 프로젝트 연결
    GAS 트리거 방치했다가 오류 폭탄 맞은 이야기 — 함수명 바꿀 때 트리거도 꼭 같이 정리하세요
    GAS 트리거 방치했다가 오류 폭탄 맞은 이야기 — 함수명 바꿀 때 트리거도 꼭 같이 정리하세요
    Notion API page_size 함정 — 우선순위 항목이 조회에서 빠지는 이유와 해결법
    Notion API page_size 함정 — 우선순위 항목이 조회에서 빠지는 이유와 해결법
    다른 블로그
    IssueLog
    IssueLog
    issuelog.jinbytes.com
    KidStory
    KidStory
    kidstory.jinbytes.com
    IT Story
    IT Story
    jinbytes.com
    이야기하는 밤
    이야기하는 밤
    story.jinbytes.com
    [eBook] 개발자로 살아간다는 것
    [eBook] 개발자로 살아간다는 것
    유료 전자책
    [eBook] FE 실무 디테일
    [eBook] FE 실무 디테일
    유료 전자책
    [미니북] FE 실무 디테일
    [미니북] FE 실무 디테일
    무료 미니북
    © Jin's Lab · J.Lab · All Rights Reserved
    jinbytes.com · Powered by Blogger