Claude Code
Agent Workflow

AI Agent에게 단순 코드 자동완성보다 큰 작업을 맡기기 시작하면 매번 비슷한 질문이 생깁니다. 이 작업은 구현 Agent가 맡을지 탐색 Agent가 먼저 볼지, 테스트는 어디까지 필요한지, 어떤 명령은 자동 실행해도 되는지, 코드 리뷰를 언제 통과시킬지, 병렬 작업이 같은 Git 상태를 서로 망가뜨리지는 않을지 사람이 계속 결정해야 합니다.

각 세션에서 그 판단을 다시 설명하면 AI 사용량이 늘수록 오히려 Context Transfer와 검수 비용이 커집니다. 그래서 반복되는 판단을 저장소에 규칙으로 남기고, 가능한 것은 Hook과 Script가 실제로 강제하도록 만들었습니다.

역할별 Agent는 `agents`, 강제 규칙은 `hooks`, 지속 적용할 원칙은 `rules`, 외부 도구 연결은 `mcp`, 실행 관측은 `otel`, 설치·검증·리포트 자동화는 `scripts`로 나눠 관리합니다.

review gate, context guard, subagent audit, test audit Hook으로 작업을 검사하고, 각 Hook의 동작을 verify script로 다시 확인합니다. 규칙 실행과 규칙 자체의 검증을 함께 구성했습니다.

모든 작업을 세세한 프롬프트로 통제하면 Agent를 쓰는 의미가 줄어듭니다. 반대로 목표만 주고 모든 판단을 풀어두면 회귀와 작업 충돌을 사람이 사후에 찾느라 비용이 커집니다. 그래서 구현 방법의 자유도는 열어두되, 테스트·Git 상태·리뷰·도구 권한처럼 실패 비용이 큰 경계를 규약으로 닫는 방향을 택했습니다.

Conductor와 Git worktree를 사용해 작업마다 별도 실행 공간을 만들고 여러 Agent를 병렬로 움직입니다. 병렬화의 단위가 단순 채팅 세션이 아니라 독립된 working tree가 되므로, 각 Agent가 파일과 Git 상태를 바꾸어도 다른 작업과 직접 충돌하지 않는 경계를 가집니다.

AI가 생성하는 코드량이 커지면 사람이 모든 diff를 기본 검수 단위로 읽는 것은 확장되지 않습니다. 그래서 테스트를 작업 경계로 활용하고, UI 작업은 Storybook과 실제 실행 화면, 프로토타입처럼 사람이 제품 관점에서 판단하기 좋은 Surface를 우선 검토합니다.

review Agent와 push gate가 자동으로 확인할 수 있는 문제를 먼저 검사합니다. 사람은 실제 제품의 동작, 설계 경계와 사용자 경험을 Storybook과 실행 화면에서 확인합니다.

Figma 링크를 설명 대신 Context로

UI 변경에서는 공식 Figma MCP와 별도 Comment MCP로 Agent가 디자인 구조와 코멘트를 직접 읽고, 기존 컴포넌트·Storybook과 비교해 수정하도록 연결했습니다. 디자인 내용을 사람이 다시 설명하던 전달 과정을 줄이기 위한 구성입니다.

자동화가 좋아졌는지를 단순한 토큰 총량으로 판단하지 않습니다. Cache Read가 큰 모델에서는 Raw Token 자체가 실제 비용이나 비효율과 같은 의미가 아니고, AI 사용량을 줄였더라도 사람이 다시 고치는 시간이 늘면 전체 생산성은 나빠질 수 있습니다.

그래서 completed task당 비용과 토큰, 요청 수, 서브에이전트 수, 경과 시간, 사람 개입량을 보고, 동시에 review round, CI 실패, regression·hotfix·rollback 같은 품질 guardrail을 함께 측정하려고 합니다.

저장소에 usage report, audit Hook, OpenTelemetry collector와 검증 script가 함께 있는 것도 이 때문입니다. 자동화가 만든 판단 흔적을 남겨야 나중에 실제로 무엇이 좋아졌는지 비교할 수 있습니다.