Gemini Task Decomposition — 복잡한 작업을 성공적으로 완수하기

공식 레퍼런스: Gemini CLI 워크플로 · Sub-agents · GEMINI.md 가이드

큰 창(Context)이 모든 문제를 해결하지는 않는다

Gemini CLI의 100만 토큰 컨텍스트는 아키텍처를 넓게 보는 데는 유리하지만, 수천 줄의 코드를 한 번에 정확하게 수정하는 능력과는 별개의 문제입니다. 작업 범위가 너무 넓으면 모델은 환각(Hallucination)을 일으키거나 세부적인 제약 사항을 놓치기 쉽습니다.

성공적인 태스크 수행을 위한 핵심은 **"전역적으로 이해하고, 지역적으로 실행하는 것"**입니다.

1단계: Plan Mode (`/plan`)를 통한 전략 수립

구현을 시작하기 전, 반드시 /plan 명령어를 통해 읽기 전용 모드로 진입하세요. 이 단계의 목표는 코드를 고치는 것이 아니라, "무엇을 고쳐야 하는지" 완벽하게 정의하는 것입니다.

전략 수립 시 질문 목록

현재 구현의 핵심 로직은 어디에 있는가?
수정 시 영향을 받는 의존성(Dependencies)은 무엇인가?
어떤 테스트 케이스를 통해 성공 여부를 확인할 것인가?
기존의 아키텍처 패턴이나 명명 규칙은 무엇인가?

2단계: 체크리스트 작성 및 동의

Gemini에게 조사 결과를 바탕으로 단계별 실행 계획을 작성하게 하세요.

사용자: "조사한 내용을 바탕으로 5단계 이내의 실행 계획을 작성해줘. 각 단계마다 검증 방법(테스트 등)을 포함해야 해."

체크리스트 예시:

src/lib/auth.ts에 새로운 권한 확인 로직 추가
- 검증: npm test auth.test.ts 실행
API 라우트 src/app/api/data/route.ts에 미들웨어 적용
- 검증: curl로 비정상 접근 시 403 응답 확인
프론트엔드 컴포넌트 LoginButton.tsx 상태 업데이트
- 검증: Storybook 또는 로컬 서버에서 시각적 확인
전체 번역 파일(messages/*.json)에 에러 메시지 키 추가
- 검증: check-locale-parity 스크립트 실행

3단계: 점진적 실행 (Surgical Edits)

한 번에 모든 파일을 수정하게 하지 마세요. 체크리스트의 한 단계를 완수할 때마다 검증 과정을 거쳐야 합니다.

replace 도구 활용: 파일 전체를 새로 쓰기보다는, 변경이 필요한 부분만 정확하게 old_string과 new_string으로 교체하게 유도하세요.
컨텍스트 유지: 작업 도중 세션이 너무 길어져 답변이 느려지거나 품질이 떨어진다면, 지금까지의 진행 상황을 /memory add로 저장하고 세션을 다시 시작하는 것도 방법입니다.

4단계: Sub-agents로 "지엽적 작업" 위임

메인 에이전트가 전체 맥락을 쥐고 있는 동안, 반복적이거나 지엽적인 작업은 Sub-agents에게 맡기세요.

generalist: "이 10개 파일의 라이선스 헤더를 최신으로 업데이트해줘."
code-review: "지금 내가 수정한 파일들에서 보안 취약점이 없는지 검토해줘."

이렇게 하면 메인 에이전트의 컨텍스트 윈도우를 깨끗하게 유지하면서 병렬로 작업을 진행할 수 있습니다.

5단계: 최종 검증과 메모리 박제

작업이 끝나면 전체 빌드와 테스트를 실행하여 부수 효과가 없는지 확인합니다. 성공적으로 마무리되었다면, 이번 작업에서 배운 "저장소 특화 규칙"을 미래의 나를 위해 기록하세요.

/memory add "이 프로젝트의 API 에러 처리는 항상 src/lib/errors.ts를 거쳐야 함."

작업 분해 프로 팁

실패부터 시작하기: 버그 수정 시, Gemini에게 먼저 "버그를 재현하는 최소 단위의 테스트 코드"를 짜게 하세요. 테스트가 실패하는 것을 본 뒤에 코드를 수정하는 것이 가장 안전합니다.
추측 금지: Gemini가 파일 경로를 추측하거나 라이브러리 버전을 짐작한다면 즉시 멈추고 grep_search나 web_fetch 도구를 사용해 사실을 확인하게 하세요.
Step-by-Step 프롬프팅: "한 번에 다 해줘" 대신 "첫 번째 단계부터 시작하자"고 지시하는 것만으로도 정확도가 30% 이상 향상됩니다.

다음에 읽으면 좋은 글

병렬 작업을 위한 효율적인 환경 구성은 Gemini Git Worktrees
자동화된 검증 루프 구축은 Headless Automation

연결된 가이드