Claude Code Workflow Kit - Technical Documentation

[01]

워크플로우 소개

이 문서는 단일 진입점 /task 슬래시 커맨드, 백그라운드 Slack 훅, 그리고 시안 인덱스를 연계하여 자연어 요청을 즉시 검증 가능한 프로덕션 코드로 전환해내는 자동화 파이프라인 지침서입니다. 복잡한 마케팅 요소를 배제하고 오직 규격, 파일 구조, 인터페이스 표준에만 집중합니다.

💡

/task 는 요청을 plan(시안 먼저) 또는 do(바로 구현) 으로 자동 분류합니다. plan 모드의 시각 산출물은 프로젝트 루트의 .output/plans/ 폴더로 격리되며, .output/plans/index.html 로 한눈에 추적할 수 있습니다.

[02]

전체 아키텍처 흐름

CORE WORKFLOW PIPELINE ARCHITECTURE 블록을 클릭하면 세부 실행 로그가 하단에 명세됩니다.

START // FOREGROUND

요구사항 지시

/task "로그인 만들자"

자연어 요청 1줄로 시작

➔

STEP 0 // CLASSIFY

plan / do 자동 분류

--mode 로 강제 가능

애매하면 1회만 질문

➔

STEP 1 // PLAN (조건부)

시안 html + 승인 게이트

idea / design 자동 판정

.output/plans/NNN-*.html

➔

STEP 2 // IMPLEMENT

구현 + 에러 체크

typecheck · lint · test

완료 보고 + 📢 Slack

초기 입력 단계

사용자가 터미널에서 신규 피처 또는 레이아웃 수정을 /task 한 줄로 제기하는 최초 시작 지점입니다. 이 요청은 Step 0 분류기로 전달되어 plan/do 경로가 결정됩니다.

[03]

/task 통합 명령어 레퍼런스

기획·개발이 하나의 진입점 /task <요청> [--mode plan|do] [--build] 으로 통합되었습니다. Step 0 분류기가 모드를 자동 결정하며, 플래그로 강제할 수 있습니다.

모드 / 플래그	분류 시그널	핵심 산출물	동작
`--mode plan`	새 화면·페이지, 큰 UI 변경, 리디자인, 톤·레이아웃·다크모드, 결정 옵션 다수	.output/plans/NNN-[slug].html	idea(신규)/design(개선) 자동 판정 → Q&A 1회 → 시안 html → 브라우저 오픈 → `승인/수정/폐기` → 구현
`--mode do`	텍스트 변경, 버그, 백엔드·로직, 작은 스타일, 명확히 작은 수정	코드 변경 + 완료 보고	시안 단계 없이 범위 파악 → 바로 구현. 방향이 2개+ 면 1회만 보강 질문
`--build`	두 모드 공통 플래그	완료 보고(채팅)	에러 체크에 프로덕션 `build` 추가. 기본은 `typecheck` · `lint` · `test` 만

🧭

분류 기준은 단 하나 — "UI 시안(html)으로 미리 보고 확인할 가치가 있는가?". 그렇다면 plan, 아니면 do. 신뢰도가 낮을 때만 AskUserQuestion 으로 plan / do / 취소 를 1회 묻습니다.

[04]

Setup 명령어

프로젝트 초기 부트스트랩, Next.js 보일러플레이트 생성, 룰셋 검증, 원페이저 초안 작성을 담당하는 전용 슬래시 커맨드 사양입니다.

실행 패턴: /setup:init 최초 1회 부트스트랩

프로젝트 루트를 스캔해 모든 /task 실행이 참조하는 단일 진실 소스 CLAUDE.md 를 생성/업데이트합니다. .output/ 스캐폴드는 만들지 않습니다 — /task plan 모드가 필요할 때 .output/plans/ 와 인덱스를 스스로 생성합니다.

- 빌드 파일 감지 (package.json / pom.xml / build.gradle / pyproject.toml / go.mod / Cargo.toml ...)

- 단일/멀티 프로젝트 자동 인식 → 하나의 루트 CLAUDE.md 로 통합

- 코드 컨벤션 · 스타일 토큰(실제 색상 값) · 빌드 명령어 추출

- Colors/Dev Commands/Reusable Components 는 /task 의 시안·빌드·재사용에 직접 사용

[05]

시안 인덱스 (.output/plans)

/task 의 plan 모드 가 생성하는 UI 시안과 그 목록입니다. 별도 빌드·서버 없이 정적 HTML 로 동작하며, plan 실행마다 인덱스가 자동 갱신됩니다.

TYPE 01

🆕 idea 시안

대상 화면/기능이 코드에 아직 없을 때. idea-template.html 기반 와이어프레임 — 문제·핵심 기능·플로우 구조.

질문 세트: 핵심 문제 · 핵심 기능 1~2 · 참고 앱/서비스.

TYPE 02

✏️ design 시안

대상이 이미 존재 → 변경 할 때. design-template.html 기반 Before/After — 변경 부분 highlight.

질문 세트: 현재 불만 · 원하는 방향 · 참고 디자인 · 변경 범위.

INDEX

📑 index.html

모든 시안을 카드 리스트로 묶는 인덱스. idea/design 배지 + 제목 + 날짜.

AUTO-ENTRIES 마커 사이에 최근 항목이 위로 삽입.

🔢

ID 채번 · 라이프사이클

.output/plans/*.html(index 제외) 개수 + 1 → NNN-[한국어slug].html. 시안 생성 후 Start-Process 로 브라우저 자동 오픈. 승인 → 구현, 수정 필요 → 재생성 후 구현, 폐기 → html 삭제 + 인덱스 항목 제거.

[06]

디렉토리 구조 및 역할

루트에 위치한 .claude/ 내부 디렉토리 맵과 개별 컴포넌트 파일의 정의입니다. 폴더를 열고 닫으며 각 컴포넌트의 상세 주석을 파악할 수 있습니다.

DIRECTORY NAVIGATOR

📁 .claude/

▼ 📁 commands/

📄 task.md

▼ 📁 setup/

📄 init.md

📄 create-nextjs.md

📄 check-nextjs.md

📄 onepager.md

▼ 📁 hooks/

⚡ slack-notify.js

▼ 📁 skills/

🎨 design-system/SKILL.md

📐 references/design.md

▼ 📁 templates/

🎨 idea-template.html

🎨 design-template.html

📄 onepager-template.html

⚙️ settings.json

🔒 settings.local.json

FILE META INSPECTOR

commands/task.md

plan/do 통합 워크플로우 명령

Step 0 분류 → (plan) idea/design 시안 + 승인 게이트 → Step 2 구현 + typecheck/lint/test 에러 체크 → 채팅 완료 보고. argument-hint: <요청> [--mode plan|do] [--build].

* 왼쪽 트리의 임의 파일을 선택하면 메타 데이터와 역할 서술이 연계 표시됩니다.

[07]

설정 및 데이터 스키마

팀 공유 설정(settings.json), 로컬 한정 비밀/권한(settings.local.json), 그리고 시안 인덱스(.output/plans/index.html)의 실제 스펙입니다.

{
  "env": {
    "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
  },
  "permissions": {
    "allow": [
      "Read", "Edit", "Write", "Glob", "Grep",
      "WebFetch", "WebSearch", "TodoWrite",
      "Bash(*)", "Agent(*)", "Task(*)",
      "mcp__claude_ai_Figma__*", "mcp__claude_ai_Notion__*",
      "mcp__claude_ai_Gmail__*", "mcp__vibe_kanban__*" /* ... */
    ],
    "deny": [
      "Bash(rm -rf /)", "Bash(sudo *)",
      "Bash(git push --force*)", "Bash(git reset --hard*)",
      "Bash(git clean -fd*)", "Bash(*DROP TABLE*)",
      "Bash(pnpm publish*)",
      "Write(**/.env)", "Write(**/*.pem)",
      "Write(**/*secret*)", "Edit(**/.env)" /* ... */
    ],
    "additionalDirectories": [ ".claude/skills" ]
  },
  "hooks": {
    "Stop": [ { "matcher": "", "hooks": [ { "type": "command", "command": "node .claude/hooks/slack-notify.js", "timeout": 10, "async": true } ] } ],
    "Notification": [ /* 동일 훅 */ ],
    "PreToolUse": [ { "matcher": "AskUserQuestion", "hooks": [ /* 동일 훅 */ ] } ]
  }
}

{
  "env": {
    "SLACK_WEBHOOK_URL": "<YOUR_SLACK_WEBHOOK_URL>"
  },
  "permissions": {
    "allow": [
      "Write(**/.output/**)", "Edit(**/.output/**)", "Read(**/.output/**)",
      "Bash(mkdir:*)", "Bash(rm:.output/**)",
      "Bash(Start-Process:*)", "Bash(start:*)"
    ],
    "additionalDirectories": [ /* 추가 작업 디렉토리 */ ]
  }
}
// .gitignore 처리 — 민감 정보 + 로컬 전용 권한

<!-- .output/plans/index.html — plan 실행마다 자동 갱신 -->
<ul class="entries"><!-- AUTO-ENTRIES-START -->
  <li class="entry">
    <a href="004-어드민-종목관리-상폐삭제.html" target="_blank">
      <span class="badge badge-idea">idea</span>
      <span class="title">어드민 종목(티커) 관리</span>
      <time>2026-06-11</time>
    </a>
  </li>
<!-- AUTO-ENTRIES-END --></ul>
// badge-idea(신규) / badge-design(개선), 최근 항목이 위로 삽입

[08]

Slack Webhook 연동 규격

slack-notify.js 가 3개 이벤트(Stop · Notification · PreToolUse(AskUserQuestion))에서 Block Kit(header/section/context) payload 를 조립해 Slack 으로 전송합니다. Webhook URL 은 settings.local.json 의 env.SLACK_WEBHOOK_URL (또는 환경변수)에서 읽으며, 미설정 시 조용히 스킵합니다.

STOP (완료) end_turn 만

{
  "text": "[project] 작업 완료",
  "blocks": [
    { "type": "header",
      "text": ":white_check_mark:  project" },
    { "type": "section",
      "text": { "type": "mrkdwn",
        "text": "<마지막 메시지 200자 요약>" } },
    { "type": "context",
      "elements": [{ "text": "14:21 | 작업 완료" }] }
  ]
}

NOTIFICATION (알림) :bell:

{
  "text": "[project] <message>",
  "blocks": [
    { "type": "header",
      "text": ":bell:  project" },
    { "type": "section",
      "text": { "type": "mrkdwn",
        "text": "" } },
    { "type": "context",
      "elements": [{ "text": "14:21 | 알림" }] }
  ]
}

ASK (질문 대기) PreToolUse

{
  "text": "[project] 응답 필요",
  "blocks": [
    { "type": "header",
      "text": ":raising_hand:  project" },
    { "type": "section",
      "text": { "type": "mrkdwn",
        "text": "*1.* 질문\n  :small_blue_diamond: 옵션 _설명_" } },
    { "type": "context",
      "elements": [{ "text": "14:21 | 응답 대기 중" }] }
  ]
}