Claude Code의 스킬을 작성할 때 유용했던 3가지 내장 도구

이 기사는 Claude on SonicGarden의 기사입니다. SonicGarden의 프로그래머가 Claude Code의 활용에 대해 쓰고 있습니다. #claude_on_sonicgarden

최근 claude-plugins로 Agent Skill을 몇 가지 만들고 있는데, 그중에서 편리하다고 생각한 내장 도구(Built-in tool) 3가지를 소개합니다.

TodoWrite

Agent

EnterPlanMode / ExitPlanMode

TodoWrite는 태스크 리스트를 만들어 진행 상황을 관리하는 도구입니다.

dev-workflow라는, 계획 → 리뷰(최대 N회) → 구현 → 체크 → 코드 리뷰(최대 N회) → 규칙 업데이트, 라는 흐름으로 Claude Code에게 개발을 시키는 스킬을 작성하고 있습니다.

처음에는 Markdown으로 「Step 1, Step 2, Step 3...」라고 나열하고 끝냈었는데, 이렇게 하면 다음과 같은 일이 흔히 발생합니다.

• 리뷰는 1번만 하고 구현으로 넘어감
• 구현 후의 체크를 건너뜀
• 태스크가 커지면 페이즈(Phase)별로 무시함

절차서는 어디까지나 참고 자료일 뿐이라, 최단 루트로 끝내버리려는 느낌입니다.

그래서 스킬의 시작 부분에서 모든 단계를 TodoWrite에 등록하도록 했습니다.

Register all workflow phases with `TodoWrite`. Do NOT skip any phase:
- Step 2: Create Plan
- Step 3: Plan Review
...

TodoWrite를 사용한 이후부터는 워크플로우를 상당히 안정적으로 실행해 주고 있습니다.

특히 리뷰 부분은 「지적이 없어질 때까지 반복한다」와 같은 지시를 하면 좀처럼 잘 작동하지 않았는데, TodoWrite를 사용하면서 상당히 안정되었습니다.

Claude Code가 워크플로우를 준수하게 만들고 싶을 때는 TodoWrite를 추천합니다.

Agent는 서브 에이전트(Sub-agent)를 기동하는 도구입니다. 메인 Claude Code와는 별개의 컨텍스트(Context)에서 독립적인 작업을 시킬 수 있습니다.

사용처는 병렬화와 컨텍스트 분리 두 가지입니다. 각각 별도의 스킬에서 사용하고 있습니다.

rules-review는 .claude/rules/에 작성된 규칙에 코드 변경이 위반되지 않았는지 체크하는 스킬입니다.

규칙 파일이 10개 이상 있으면, 전부를 한 번에 체크하게 하기에는 정보량이 너무 많습니다. 그래서 규칙을 카테고리별로 그룹화하여, 각각을 별도의 Agent가 보게 하는 구조로 만들었습니다. 각 에이전트가 보는 규칙과 차이점(Diff)을 좁힘으로써 리뷰 정밀도를 높이는 것이 목적입니다.

Launch one Agent per group **in parallel** (use a single message with multiple
Agent tool calls).
Before launching Agents, **prepare the data to embed in each prompt**:
...

이것을 Agent로 병렬 실행(1개의 메시지에 여러 개의 호출을 포함)함으로써, 3~5개 그룹으로 나누더라도 거의 1회분 정도의 시간으로 체크가 끝납니다. 책임을 나누면 보통 시간이 늘어나기 마련이지만, 병렬화를 통해 거의 제로 코스트(Zero cost)로 만들 수 있는 것이 Agent의 장점입니다.

extract-rules의 --from-conversation은 세션의 .jsonl(대화 이력의 로우 데이터)을 분석하여 규칙을 추출하는 모드입니다. 이것을 메인에서 수행하면 다음과 같은 문제가 생깁니다.

• .jsonl이 수 MB ~ 수십 MB에 달해 컨텍스트를 많이 소비함
• 분석 후의 결과만 있으면 되는데, 중간 과정의 로그가 계속 남음

따라서 무거운 처리는 통째로 Agent에게 던지는 구조로 만들었습니다. 메인은 「추출해 둬」라고 의뢰하기만 하면 되고, jsonl 분석·분류·규칙 추가는 전부 Agent 측에서 완결되며, 돌아오는 것은 요약(Summary)뿐입니다.

이 「무거운 처리는 서브 에이전트에게 통째로 맡기고 요약만 받는다」 패턴은 스킬을 작성할 때 가장 자주 사용하는 방식일지도 모릅니다.

솔직히 자주 사용하는 것은 위의 두 가지이며, 세 번째는 기사로서 조금 부족했기에 넣었습니다. 다만, 이런 것도 할 수 있다는 소개로서 말입니다.

EnterPlanMode / ExitPlanMode

은 스킬로부터 Plan Mode로의 출입을 제어하는 도구입니다. Plan Mode 중에는 편집 계열 도구를 사용할 수 없으므로, "계획을 세운 뒤 구현에 들어간다"라는 흐름을 강제할 수 있습니다.

dev-workflow

저는 계획 작성 단계에서 EnterPlanMode를 실행하게 하고, 사용자가 계획을 승인할 때까지 ExitPlanMode를 실행하지 않도록 하는 방식으로 사용하고 있습니다.

### Step 2: Create Plan
1. `EnterPlanMode`
2. Analyze the task and codebase, create implementation plan
...

"계획을 세워주세요"라고만 적으면, 계획을 내놓자마자 바로 구현으로 돌입해버리는 경향이 있습니다. Plan Mode에 진입시켜 두면 편집 도구를 물리적으로 사용할 수 없기 때문에, 그러한 사고가 일어나지 않습니다. 용도는 한정적이지만, 계획 승인 게이트(gate)를 삽입하고 싶은 스킬에서는 매우 유용합니다.

도구	사용할 때
TodoWrite	플로우(flow)를 준수하게 하고 싶을 때. 반복 횟수를 고정하고 싶을 때
Agent	책임을 분리하여 정밀도를 높이고 싶을 때, 메인 컨텍스트 (context)를 오염시키고 싶지 않을 때
EnterPlanMode / ExitPlanMode	구현 전에 사용자 승인을 거치고 싶을 때

다만, 이것들을 지정했다고 해서 완벽하게 준수되는 것은 아닙니다. TodoWrite에 전부 나열해 두어도 도중에 탈선할 수 있으며, Agent에 넘긴 처리가 미묘하게 기대와 다르게 돌아올 수도 있습니다. 그럼에도 불구하고, Markdown만으로 작성했을 때와 비교하면 동작의 안정감이 상당히 다릅니다.

이번에 언급한 스킬은 아래 리포지토리(repository)에 공개되어 있습니다.

hiroro-work/claude-plugins

• dev-workflow: 계획 → 리뷰 → 구현 → 체크의 흐름을 돌리는 스킬
• rules-review: .claude/rules/에 대한 준수성 체크
• extract-rules: 코드베이스, 대화, PR로부터 규칙을 추출

이 기사는 Zenn/Qiita에 크로스 포스트(cross-post)하고 있습니다.