나의 에이전틱 엔지니어링 워크플로우 (My Agentic Engineering Workflow)

도구 (Tools)

전체적인 비교와 맥락은 저의 2026 AI 기술 스택 포스트에서 확인하실 수 있습니다. 여기에는 아래의 워크플로우를 따라가는 데 필요한 설치 항목들만 나열되어 있습니다.

Claude Code

처음 접하신다면, 치트 시트 (cheat sheet)와 Anthropic 권장 사항 (best practices)부터 시작하세요.

보안 (Security) — 이것부터 먼저 설정하세요:

• Claude Code Security Hooks — 7계층 프롬프트 인젝션 (prompt injection) 방어, 읽기 가드 (read guards), 카나리 파일 (canary files)
• 다른 무엇보다 먼저 .env 파일과 모든 git-secret 파일을 .claude/settings.local.json에서 잠그세요.

MCP:

• Context7 — 온디맨드 라이브러리/API 문서
• DeepWiki — 오픈 소스 저장소 (repo) 문서화

기술 (Skills):

• Matt Pocock의 기술 세트 (skill set) — /grill-me, /handoff, /improve-codebase-architecture (아래에서 자세히 다룸)
• Understand Anything — 대화형 코드 지식 그래프 (knowledge graphs)
• Ponytail — 가장 게으른 시니어 개발자 휴리스틱 (laziest-senior-dev heuristic), /improve-codebase-architecture와 잘 어울림

에이전트 (Agents):

• DocsExplorer — 메인 컨텍스트 (context)를 오염시키지 않고 서브 에이전트 (subagent)에서 문서 조회를 처리함

훅 / 프록시 (Hooks / proxies):

• rtk — 토큰 감소 프록시 (token reduction proxy), 단일 Rust 바이너리

UI:

• Claude HUD — 모델, 컨텍스트 크기 (context size), 활성화된 도구 및 에이전트를 보여주는 상태 표시줄 (status bar)

기타 도구 (Other tools)

• JetBrains — git, 디버깅 (debugging) 및 Claude의 변경 사항 검토 (reviewing) 용도; Claude Code plugin
• Warp.dev — 터미널 (terminal); hands-off 작업에는 Warp Oz, hands-on 작업에는 Claude Code 사용

프로세스 (Process)

이전 포스트에서 언급했듯이, 저의 워크플로우는 일반적으로 여러분이 하이프(hype)나 소셜 미디어 게시물에서 보게 되는 것과는 매우 다릅니다. 저는 보통 모노레포 (monorepo), 단일 스택 (single stack), 단일 언어 프로젝트에서 작업하지 않습니다. 저의 클라이언트들은 대개 여러 언어와 스택을 사용하는 완전한 마이크로서비스 (microservices) 형태입니다. 게다가, 저는 화려한 플러그인 방식의 텍스트 에디터보다 IDE를 선호하며, 이는 종종 제가 모든 프로젝트를 단일 스코프 (single scoped)로 유지할 수 없음을 의미합니다.

이것이 의미하는 바는 Air, Conductor, Antigravity와 같은 현재의 인기 도구들이 저에게는 맞지 않는다는 것입니다.

그래서 저는 저만의 문제를 직접 해결해 왔으며, 오늘 공유하는 이 프로세스는 제가 하나의 목표를 향해 서로 다른 레포지토리 (repos)에서 주로 독립적으로 작동하는 여러 에이전트 (agents)를 활용할 수 있게 해줍니다. 저는 에이전트를 주니어 개발자나 계약직 직원처럼 대합니다. 즉, 신뢰하되 검증 (trust but verify)합니다. 그들에게 작업을 부여하지만, 최종 승인 (sign-off)은 제가 합니다.

폴더 및 워크트리 (Folders and Worktrees)

이것은 제가 배운 핵심적인 요소 중 하나입니다. 프로젝트가 서로 다른 마이크로서비스를 위해 다섯 개의 서로 다른 레포지토리를 가지고 있다고 가정해 봅시다. 그중 일부는 trunk 기반이고, 다른 것들은 feature 브랜치를 사용하지만, 이는 중요하지 않습니다. 다만 항상 돌아갈 수 있는 기본 메인 브랜치 (main branch)가 있다고 가정합니다. 저는 이들을 ~/Source/mains에 보관하여, 항상 동기화하고 되돌릴 수 있는 단일 진실 공급원 (source of truth)을 유지합니다.

~/Source/mains/
├── CLAUDE.md
├── repoA           <--- 프론트엔드 (frontend)
...

각 레포지토리에는 에이전트를 위한 컨텍스트 (context)와 지침 (instructions)이 포함된 CLAUDE.md 파일이 있습니다. 이곳에 에이전트가 알아야 할 특정 지침이나 컨텍스트를 추가할 수 있습니다. 이상적으로는 README뿐만 아니라 프로젝트와 관련된 기타 사양 (specs)이나 ADR (Architecture Decision Records)을 참조하도록 구성합니다.

정말 운이 좋다면 참조할 수 있는 .understand-anything 폴더가 있을 수도 있지만, 무엇보다도 제가 가장 먼저 시도하고 추가하는 것 중 하나는 모든 리포지토리(repos)와 다른 CLAUDE.md 파일들을 하나로 묶어주는 루트 디렉토리의 CLAUDE.md를 만드는 것입니다.

기능 구현 (Implementing Features)

자, 이제 기능 요청(feature request)이 들어왔고, 이것이 여러 리포지토리에 걸쳐 있을 것이라고 가정해 봅시다. 예를 들어 두 개의 마이크로서비스 (B와 C) 및 하나의 공유 라이브러리 (E)에 영향을 미친다고 가정하겠습니다. 저는 팀이 따르는 브랜치 명명 규칙에 따라 해당 기능(feat1이라고 부릅시다)을 위한 워크트리(worktrees)를 ~/Source/worktrees에 생성하는 것으로 시작합니다. 이를 통해 충돌을 걱정할 필요 없이 여러 기능이나 버그를 동시에 작업할 수 있습니다.

~/Source/worktrees/
└── feat1
    ├── repoB
...

예를 들어, 리포지토리 A와 C를 건드려야 하는 프론트엔드 버그 수정(frontend bug fix)도 필요하다고 가정해 봅시다. 저는 해당 기능(bugfix1이라고 부릅시다)을 위한 또 다른 워크트리를 생성하여 병렬로 작업할 수 있습니다.

~/Source/worktrees/
├── bugfix1
│   ├── repoA
...

계획 및 조정 (Planning and Coordination)

좋습니다, 지금까지는 꽤 지루한 내용이었지만 이제 마법이 시작됩니다. 워크트리에 모든 리포지토리를 설정했으므로, 이제 구현을 계획하고 조정하기 시작할 수 있습니다. 이를 위해 저는 보통 메인 디렉토리에서 새로운 claude 세션을 시작합니다. 왜일까요? 그 세션이 모든 컨텍스트(context)를 가지고 있기 때문입니다. 만약 제가 초기 평가에서 무언가를 놓쳤다면, 세션이 무엇을 놓쳤는지 알려주고 공백을 채울 수 있도록 도와줄 수 있습니다.

그래서 저는 새로운 세션을 시작하고, Plan Mode로 전환합니다 (저는 /model opusplan 모드를 사용하며, 계획을 세우는 데 가장 최적화된 모델을 사용하고 싶기 때문입니다). 그런 다음 이미 PRD(제품 요구 사항 문서)가 있다면 /grill-me 또는 /grill-with-docs로 시작하여, 제안된 계획이 마음에 들 때까지 함께 검토하며 다듬어 나갑니다. 하지만 이 세션이 컨텍스트 과부하로 인해 직접 작업을 처리하는 것은 원치 않으므로, 대신 다음과 같은 명령을 내립니다.

/handoff 각 에이전트가 개별 리포지토리 (repo)를 처리할 것이므로, 각 에이전트가 자신의 부분을 독립적으로 처리할 수 있도록 계획 (plan)에서 충분한 컨텍스트를 추출하여 핸드오프 문서 (handoff doc)를 생성하라

이렇게 하면 각 에이전트 세션의 컨텍스트 (context)를 과부하시키지 않으면서, ~/Source/worktrees/feat1/handoff.md에 복사하여 구현을 조정하는 데 사용할 수 있는 핸드오프 문서 (handoff document)가 생성됩니다.

다음 부분은 중요합니다. 저는 메인 세션 (mains session)을 열어둔 상태로 유지하고, /clear를 실행하여 처음부터 다시 시작합니다. 이 세션은 저의 오버워치 (overwatch) 역할을 합니다. 이 세션은 전체적인 그림 (big picture)을 파악하고 있으며, 문제가 발생했을 때 에이전트들을 조정할 수 있습니다.

~/Source/
├── mains               <---- 오버워치 (Overwatch) 세션이 여기서 실행됨
│   ├── CLAUDE.md
...

좋습니다, 그럼 이제 실제로 작업을 진행해 봅시다.

실행 (Execution)

이 단계는 구현의 복잡도에 따라 다소 달라질 수 있지만, 일반적으로 워크트리 (worktree) 내의 각 리포지토리 (repo)에 대해 새로운 claude 세션을 생성하는 것부터 시작합니다. 이때 해당 세션이 핸드오프 파일 (handoff file)에 접근할 수 있는 권한을 갖도록 확인합니다. 그런 다음 복잡도에 따라 각 에이전트에게 다음 중 하나를 수행하도록 합니다.

단순한 작업의 경우:

/goal 당신은 [repo name]을(를) 가지고 있습니다. @handoff.md를 살펴보고 무엇을 구현할지 결정한 뒤, 당신에게 설정된 기준 (criteria)에 따라 스스로를 점검하세요.

약간 더 어려운 작업의 경우, 플랜 모드 (Plan Mode)로 전환합니다:

당신은 [repo name]을(를) 가지고 있습니다. @handoff.md를 살펴보고 무엇을 구현할지 결정한 뒤, 제가 검토할 수 있도록 계획 (plan)을 제시하세요. 불확실한 부분은 질문하세요.

이미 앞 단계에서 수행했으므로 여기서는 /grill-me를 다시 사용하지는 않습니다. 핸드오프 문서 (handoff doc)에 필요한 모든 컨텍스트 (context)가 포함되어 있어야 하기 때문입니다. 계획 (plan)을 받은 후에는 에이전트 간의 교차 조정 (cross coordination)이 필요한지 확인합니다. 만약 필요하다면, 메인 오버워치 (overwatch) 세션으로 돌아가 검토를 요청합니다. Claude는 기본적으로 모든 계획 (plans)을 ~/.claude/plans/에 저장하기 때문입니다.

~/.claude/plans/
└── you-are-investigating-the-snuggly-sundae.md

당신이 생성한 @handoff.md 기반의 인수인계(handover)를 바탕으로 두 에이전트가 [우리가 논의한 기능]을 작업하고 있습니다. 각 에이전트의 개별 계획을 검토하고 상호 의존성(cross dependencies)을 조정해 주세요. 계획 파일은 [@plan_for_repoB.md]와 [@plan_for_repoC.md]입니다. 필요한 경우 계획 파일을 업데이트하세요.

업데이트 사항이 있다면, 저는 다시 에이전트들에게 돌아가 업데이트 내용을 검토하게 한 뒤, Auto Accept(자동 승인) 모드로 진행하기 전에 다시 프롬프트를 입력하도록 합니다. 저는 이미 계획을 검토했고, 다양한 보안 체크와 훅(hooks)이 설정된 Claude 환경을 갖추고 있기 때문에 이 모드를 편안하게 사용합니다. 두 번 측정하고 한 번 자르는 법이죠(Measure twice, cut once).

테스트 및 검증 (Testing and Validation)

이 부분은 프로젝트와 테스트 전략에 따라 크게 달라지므로 너무 길게 설명하지는 않겠습니다. 일반적으로 저는 에이전트들이 유닛 테스트(unit tests)를 실행하고 통과하는지 확인하도록 합니다. 문제가 발생하면 다시 에이전트들에게 돌아가 문제를 수정하도록 합니다.

UI 관련 작업의 경우, Playwright를 사용할 수 있다면 MCP 서버를 사용하여 에이전트가 실행하도록 하고, 그렇지 않으면 결국 수동으로 테스트하게 됩니다. 결국 코드의 품질에 대한 책임은 여전히 저에게 있으며, 풀 리퀘스트(pull request)나 머지 리퀘스트(merge request)를 기록하기 전에 코드가 양호한지 반드시 확인해야 합니다.

여기서 중요한 부분은 실제로 무언가 잘못되었을 때입니다. 검토 목적으로 두 에이전트 모두 고장 난 부분에 대한 컨텍스트(context)가 필요한 시나리오가 발생할 수 있기 때문입니다. 이 경우 저는 예를 들어 ~/Source/worktrees/feat1에서 새로운 리뷰어 세션을 시작하고 다음과 같이 말합니다.

서로 다른 Claude 에이전트들이 @handoff.md의 기능을 구현했으며, 현재 [버그 또는 이슈]가 발생하고 있습니다. 이를 조사하고 수정해 주세요. 당신은 모든 관련 리포지토리(repos)에 접근할 수 있으며, 컨텍스트가 필요한 경우 @/.claude/plans/[plan name 1].md 및 @/.claude/plans/[plan name 2].md에 있는 계획을 확인할 수 있습니다.

이렇게 하면 깨끗한 상태(clean slate)에서 문제를 조사할 수 있어, 컨텍스트 윈도우(context window)의 '좋은' 부분으로 다시 돌아갈 수 있으며, 한 곳 이상의 장소에서 변경이 필요한 경우 리포지토리 간의 상호 조정(cross repo coordination)도 가능해집니다.

~/Source/worktrees/
├── bugfix1
│   ├── repoA
...

테스트가 잘 진행되었더라도, 저는 보통 적어도 한 번은 이 명령어를 실행합니다:

이 리포지토리의 마지막 git diff와 커밋들을 검토하고, 구현 내용을 @handoff.md와 비교하여 누락되었거나 잘못된 부분이 있는지 강조해 주세요.

개선 사항 (Improvements)

덧붙이자면, 제가 시도해 보고 있지만 아직 원하는 대로 완벽하게 작동하지는 않는 기능이 바로 /loop입니다. 이것은 꽤 멋진 기능인데, 프롬프트나 슬래시 명령어(slash command)를 반복적인 간격으로 실행할 수 있습니다 (예: /loop 5m /foo). 제가 시도해 본 방식은 각 리포지토리의 CLAUDE.md에 다음과 같은 내용을 작성하는 것이었습니다:

"만약 작업 중 막히거나 상위 수준의 질문에 대한 답변이 필요하다면, 질문을 @~/Source/mains/feat1-questions.md 파일에 작성하세요."

그러면 저는 오버워치(overwatch) 세션에서 새로운 질문이 있는지 확인하고 동일한 파일에 답변을 작성하는 루프(loop)를 실행합니다. 답변이 완료되면, 워커 에이전트(worker agent)에게 답변을 확인하고 작업을 계속하라고 지시할 수 있습니다. 저는 이 아이디어가 정말 마음에 들지만, 항상 제가 원하는 대로 작동하지는 않습니다. 그럼에도 불구하고, 이는 멋진 조정(coordination) 실험입니다.

이상적으로는 단지 /loop 5m look at @~/Source/mains/feat1-questions.md and if your question is answered continue with your work (5분마다 @~/Source/mains/feat1-questions.md를 확인하고, 질문에 대한 답변이 있으면 작업을 계속하라)와 같이 작동한다면 정말 놀라울 것입니다. 하지만 아쉽게도 아직 일관되게 작동하도록 만드는 데는 성공하지 못했습니다.

요약 (Summary)

세상에, 정말 말이 많은 블로그 포스트였네요. 결국 저에게 있어 핵심은 에이전트를 마치 사람처럼 다루는 것입니다. 만약 제가 두 명의 주니어 개발자에게 서로 다른 리포지토리를 맡겼다면, 미드(mid) 또는 시니어(senior) 개발자가 그들의 작업을 검토하게 하고, 리드(lead) 또는 PM이 그들의 노력을 조정하도록 했을 것입니다. 궁극적으로 이 모든 것은 제가 CAST를 제대로 작동시킬 때까지 사용하는 수동적인 임시방편일 뿐입니다.

이 접근 방식에서 제가 또한 좋아하는 점은 Claude만을 사용하도록 제한하지 않는다는 것입니다. 기술(skills)을 설치할 수 있고 보안 요소(security bits)가 갖춰진 하네스(harness)라면 무엇이든 사용할 수 있습니다. 저는 IDE와 에디터, 사용하는 하네스, LLM 모델 등 그 모든 것을 교체할 수 있습니다. 도구보다 프로세스가 더 중요합니다.

이를 통해 여러분이 Claude Code를 사용하여 어떻게 더 생산적으로 일할 수 있는지에 대한 몇 가지 아이디어를 얻으셨기를 바랍니다. 분명 더 나은 방법들이 있을 것이며, 저는 항상 피드백과 제안을 기다리고 있습니다. 제가 찾은 가장 유사한 것은 아마도 Steve Yegge의 Gas Town일 것이며, 구조적인 방식에서 어느 정도 겹치는 부분이 있습니다. 다른 제안이나 질문이 있으시다면 Twitter나 LinkedIn을 통해 저에게 연락해 주세요. 그동안 즐거운 코딩 하시길 바랍니다.

이 포스트는 Harper Reed의 글과 같은 다른 게시물들, NetNineNine 팀원들과의 논의, 그리고 CAST 작업으로부터 영감을 받았습니다.