[Claude Code] AI 워크플로우 플러그인 Arc 만들기 #1

들어가며 - AI 코딩 에이전트

Claude Code, Codex, Gemini CLI, Cursor, Windsurf...

AI 코딩 도구가 쏟아지는 시대다. 나는 그중에서 Claude Code를 메인 도구로 사용하고 있다. 터미널에서 자연어로 코드를 작성하고, 파일을 수정하고, git 커밋까지 하는 그 흐름이 작업 방식과 맞았기 때문이다.

Claude Code 에는 플러그인, 에이전트, 스킬이라는 확장 시스템이 있다. 이걸 잘 조합하면 워크플로우를 자동화할 수 있겠다고 생각했다. 그래서 이것저것 사용해 봤다.

• https://github.com/wshobson/agents - Claude Code Plugin 모음으로 높은 star를 받은 레포지토리이다. Plugin 기반으로 역할에 따른 여러 플러그인을 제공한다. 플러그인 내부에 여러 Agent와 Skill 이 포함되어 있는 구조이다.
• https://github.com/popup-studio-ai/bkit-claude-code - 콘텍스트 엔지니어링을 도와주는 claude code plugin으로 PDCA 방법론을 통해 구조화된 개발 워크플로우를 만들어준다.

이 플러그인 저 플러그인 다 추가하면서 방법도 모르고 사용하다 보니 역시 깨닫게 되었다.

 

도구가 많다고 생산성이 높아지는 건 아니다.

---

다른 사람이 만들걸 가져다 쓰기

. claude 디렉터리를 정리해 봤다. 

에이전트: 4개
스킬: 26개
플러그인: 5개
훅: 5개

플러그인에 속한 subagent는 카운트가 되지 않은 숫자인데도 너무 많았다. 이중 실제로 내가 인지하고 워크플로우에 사용하는 스킬과 에이전트는 5개도 되지 않았다. 

나머지는 전부 일단 넣어두면 쓰이겠지라며 추가된 것들이었다. 한두 번 써보고 방치된 것들이 대부분이었다.

사용하지 않는 자산은 도움이 아니라 인지 부하다.

스킬 목록과 에이전트가 길어질수록 추론을 통한 선택의 비용이 늘어난다. 많은 수의 스킬과 에이전트는 골라야 하는 선택지가 너무 많아지는 것이다. 3개만 있으면 선택지가 적어 선택에 드는 비용이 줄어든다. 

 

엔터프라이즈 플러그인의 블랙박스

bkit 정말 잘 만들어진 플러그인이다.

bkit를 분석해 보니 구조 설계가 정말 잘 되어 있었다. 'plugin.json'으로 메타데이터를 관리하고, 에이전트와 스킬을 분리하고 훅으로 이벤트 제어를 하여 체계적으로 작동하는 아키텍처이다.

그러나 문제가 있었다. 전체적인 작동 방식을 이해하지 못한 상태에서 사용하려니 어떤 메커니즘으로 어떤 결과를 만드는지 알 수 없었다.

에이전트가 생성되고 스킬이 호출되고 훅이 개입하는 전체 파이프라인을 그냥 사용하기엔 내가 이해하는 바가 너무 낮았다. 어떻게 사용하면 좋을지 AI에게 물어보고 사용해 봤지만 사용하는 사례가 너무 많은 토큰을 사용하고, 프로세스가 너무 복잡하게 느껴졌다.

 

AI를 잘 사용하는 나

AI 를 잘 통합해서 나의 생산성을 올리고 이를 내 삶을 레버리지하는 도구로 잘 사용하는 것이 나의 욕심이다. 이 욕심을 채우기 위해서 여러 영상을 보고 여러 방법론은 접하고 여러 방식을 확인해 본 결과, AI의 과도기인 지금 이 기술을 나 스스로 얼마나 높은 이해도를 가지고 사용하냐에 달려있다. 이론은 정말 많지만, 실제로 해보지 않으면 이해하지 못하는 영역이다.

인스턴트적인 접근법들 (AI에게 물어보고 딸깍이나, 영상을 겉핥기식으로만 따라 하는 방법) 은 결국 내가 가진 능력치를 올려주는 것이 아니었다. 적용해 보고 처음엔 엄청난 생산성 향상을 경험하는 것처럼 느끼다가도, 금세 흥미가 떨어지고 Claude Code와 핑퐁으로 돌아간다. 

이것들에 대한 실험 결과도 없고 기록도 없으니 개선점이나 히스토리 관리는 안되고 단순 시도들만 늘어나 지식은 쌓이지 않고 체계화되지 않는다. 결국 다양한 기술을 사용하거나 새로운 방식을 접할 때 이건 이래서 좋은데 이건 이래서 싫어라는 기준이 될 수 있는 판단 근거가 없게 되었다.

내가 가진 AI 활용 능력은 상승한 게 아닌 오히려 복잡만 해졌다. 그래서 나는 AI를 내 삶을 레버리지 하기 위해서 처음부터 만들어보기로 결정했다.

---

맨바닥부터 만들자. 다만 레퍼런스를 곁들여

이것저것 등록해 놓은 Claude Code의 skill과 plugin, agent의 frontmatter 정보를 로드하는 데 사용하던 토큰은 초기 26% 였다.

Auto compact를 사용 시 16.5 % 의 버퍼를 더하면 아무것도 안 하고 세션 시작만 했을 때, 약 42.5% 의 콘텍스트를 떼고 작업을 시작하는 것이었다. 그래서 항상 토큰이 부족했다. 조금만 작업이 길어지고, 문서나 코드를 읽을 양이 늘어나면 제대로 작업을 시작하기도 전에 Compact 가 일어나는 경우도 있기도 했다.

옛것은 다 지워버렸다. 일단 에이전트, 스킬, 플러그인, 훅을 전부 비활성화 및 삭제하였다. 초기 토큰 점유율을 줄이기 위해서이다. 그리고 정말 사용하는 것들만 남겨두기로 결정했다.

• 기존 mcp - AWS Document, Confluence, Sequential thinking 은 평소에도 너무 잘 사용하는 mcp이다.
• Git, Jira, Notion 등 Skill - 업무에 통합되는 도구들은 역시 원하는 방향으로 상당한 커스텀이 되어 있기 때문에 유지한다.

그리고 bkit를 레퍼런스 삼아서 나의 워크플로우에 통합될 수 있는 플러그인을 만들기로 정리했다.

---

Arc로 해결하려는 것

그렇게 Arc 플러그인을 만들기 시작했다.

Arc 플러그인은 Agentic 한 워크플로우로 확장되게끔 만드는 게 목표이다. 그래서 AI 워크플로우에 대한 방법이 가장 중요했다. 루프를 돌면서 목표한 작업을 완수해 가는 Agentic 워크플로우에 기반하여 " X라는 기능을 구현할 거야. 이를 위한 작업 진행해 줘 "라는 요청으로 기획 -> 구현 -> 검증 -> 문서화의 일관된 흐름으로 진행될 수 있게 워크플로우를 구성한다.

 

에이전트가 아닌 스킬을 선택

Claude Code의 확장 시스템에는 에이전트와 스킬이 있다. 

• 에이전트: 별도의 세션을 시작하며, 시스템 토큰과 선언된 도구에 대한 내용을 콘텍스트로 포함하여 시작된다. 별도의 세션에서 시작되기 때문에 별도의 콘텍스트를 사용하게 된다. 메인 세션에서 입력을 받아서 처리한 결과를 메인 세션으로 전달한다.
• 스킬: 명시적으로 호출(user-invocable)하거나 패시브 스킬처럼 참조하는 타입 두 가지가 있다. 메인 세션에서는 frontmatter에 포함된 description 만 로드하며, 필요에 따라서 스킬을 호출하거나 참조하여 사용할 수 있다.

별도의 세션에서 실행되는 적합한 작업은 메인 세션에서 사용했을 때 토큰을 낭비하게 되는 파일을 읽는 작업, 로그를 분석하는 작업이나 병렬로 처리할 수 있는 의존성이 없는 작업등이 있을 수 있다. 다만 이런 작업 흐름은 구현이나 디버깅 혹은 문서화와 같은 특정 작업의 단계에 필요하며 실제 작업을 할 때는 Claude와 핑퐁을 치면서 지시적으로 작업하는 부분이 더 많았다.

따라서 기획, 구현, 검증, 문서화와 같은 각 단계는 명시적으로 호출하는 스킬로 분류했다. 현재 하려는 작업이 어느 단계에 있는지를 명시적으로 선언하고 호출함으로써 에이전트가 작업 흐름을 판단하는 과정을 줄인다. 여기에 구현과 검증 단계에서는 내부적으로 Agent를 병렬로 호출할 수 있다. 이를 위한 구현 전용 에이전트와 검증 전용 에이전트를 호출 가능한 구조를 가진다. 

 

HardGate - 방향 선택은 사람이

AI는 자율성을 가지고 작업한다. 다만 자율성은 올바른 가드레일이 있을 때 빛을 발할 수 있으며, 올바른 방향성일 때 결과의 차이를 만들 수 있다. 따라서 Arc는 모든 라이프 사이클 단계에서 사람의 개입의 선택을 둔다.

Agentic 한 워크플로우에서 이런 결정은 비효율처럼 보일 수 있다. 하지만 올바르지 않은 방향으로 작업된 내용을 되돌리는 비용은 중간에 게이트를 통한 인간의 검증이 들어가는 것보다 비용이 항상 크다고 판단했다. 이 원칙은 경량 작업을 진행하는 도구에서도 유지된다. 간단한 작업을 위한 스킬을 호출할 때도 영향받는 파일과 예상 변경점을 보여주고 승인을 받고 진행한다. 경량이지 무책임이 아니다.

 

소크라테스 질문 - AI가 사람에게 묻는 구조

보통 AI 도구를 쓸 때, 사람이 질문하고 AI가 답한다. Arc의 Plan 스킬은 이 관계를 뒤집는다.

`/arc:plan API 인증 모듈 추가`라고 입력하면, AI는 바로 Plan을 쓰지 않는다. 먼저 두 가지 관점으로 질문한다.

• Context 렌즈 - 왜 이 작업이 필요한가?
  • 발견 경위: 모니터링에서? 사용자 리포트? 코드 리뷰?
  • 이전 시도: 이전에 비슷한 시도가 있었는지
  • 촉발 요인: 왜 지금인지
• Requirements 렌즈 - 무엇을 해야 하는가?
  • 문제 정의, 대상, 제약, 성공 기준, 스코프

단순한 정보 수집이 아닌 사용자가 자기 요구사항을 명확하게 인식하도록 유도하는 과정이다. 다만 질문은 최대 2-3개로 제한한다. 이미 요청에 충분한 정보가 있으면 질문 없이 바로 진행한다. 과도한 질문은 또 다른 인지 부하다.

---

아키텍처

하이브리드 XML - 스킬 문서의 구조

각 스킬 문서(SKILL.md)는 YAML frontmatter + XML 태그 혼합 구조로 되어 있다.

Frontmatter (한글) - 사용자에게 보이는 메타데이터

---
name: plan
description: "[Arc] 기획 스킬. 사용자의 기능 요청을 소크라테스 질문으로 분석하여..."
role: "플래너 — 기능 요청을 받아 요구사항 정의, 접근법 탐색, 태스크 분해까지..."
user-invocable: true
allowed-tools:
  - Read
  - Write
  - AskUserQuestion
  - Agent
---

 

본문 (영문 + XML 태그) - AI가 실행하는 지침

<role>
You are the Arc Planner.
Analyze feature requests, define requirements through Socratic questioning...
</role>

<workflow>
## Step 1: Initialize
...

<rules>
- Title must be under 20 characters
- If existing tasks are in progress: show the task list and ask
</rules>
</workflow>

<constraints>
## HARD GATE — Execution Approval
After the plan document is written, do NOT execute any tasks
without explicit user approval.
</constraints>

 

XML 태그는 LLM의 지침 경계 인식을 돕는다. <rules> 안에 있는 내용은 "반드시 지켜야 할 규칙"으로, <workflow> 안에 있는 내용은 "순서대로 따를 절차"로 해석한다. Markdown의 `##`만으로는 이 구분이 모호해진다. 실제로 XML 태그 구조가 LLM의 지침 준수율을 높인다는 연구 결과도 존재한다. 참고할 만한 유튜브 영상도 있다.

본문이 영문인 이유는 Claude는 영어 학습 데이터가 압도적으로 많다. 같은 지침이라도 영문으로 작성했을 때 더 정확하게 따른다. Frontmatter는 사용자에게 보이는 부분이니 한글로 유지하고, AI가 실행하는 지침은 영문으로 사용하도록 실용적인 타협점을 잡았다.

 

상태 관리 — index.json과 state.json

Arc는 두 개의 JSON 파일로 상태를 관리한다. 대상 프로젝트의 `. arc/` 디렉터리에 생성된다.

`index.json` - 전체 작업 목록, 현재 모드, 활성 작업

{
  "version": 1,
  "active": "a1b2c3d4",
  "mode": "solo",
  "tasks": {
    "a1b2c3d4": { "title": "API 인증 모듈", "phase": "plan" },
    "e5f6g7h8": { "title": "모니터링 대시보드", "phase": "plan" }
  }
}

 

`states/<uuid>. state.json` - 개별 작업의 상세 이력

{
  "id": "a1b2c3d4",
  "title": "API 인증 모듈",
  "phase": "plan",
  "artifacts": {
    "plan": ".arc/plans/a1b2c3d4-api-auth.plan.md"
  },
  "history": [
    { "event": "initialized", "timestamp": "2026-03-01T10:00:00" },
    { "event": "plan drafted", "timestamp": "2026-03-01T10:15:00" },
    { "event": "plan approved", "timestamp": "2026-03-01T10:16:00" }
  ]
}

 

state와 index를 통해 작업한 내용들에 대해서 작업을 연결된 상태로 이어서 할 수 있다. artifacts에 산출물 정보가 작성되고, history를 보고 어떤 이벤트를 진행했는지 파악한다. 기억에 의존하지 않고 파일 기반으로 작업 내용을 기록하고 추적한다.

---

과정에 대한 기록

Phase 1에서 Plan과 상태 관리만 만들었다. Phase 1을 충분히 쓰면서 "Plan 질문이 너무 얕다", "접근법 탐색이 단선적이다", "Plan 없이도 할 수 있는 간단한 작업이 너무 많다"는 부족함이 체감됐을 때, 그때서야 Phase 2를 설계했다.

Phase 2에서도 Design/Decision을 만들었다가, 실제로 안 쓴다는 걸 확인하고 삭제했다. Phase 2에서 실제로 살아남은 것은 Plan의 강화(문맥 수집, 발산적 사고, Devil's Advocate)와 Do 스킬이다. Phase 3에서는 구현 가이드(Impl)와 다관점 검증(Verify)이 추가되면서, Plan → Implement → Verify 라이프사이클이 실제로 나의 워크플로우로 사용되기 시작했다.

이 블로그 글에선 완성된 도구를 소개하는 것이 아니라, 만들어가는 과정을 기록하는 것이다. 다음에는 현재까지 구현된 skill과 어떤 결정들을 통해서 어떻게 설계되고 작동하는지 기록하자.