이 기사에 대하여

Claude Code로 개발을 계속하다 보면, "프로젝트 파악 → 태스크 설계 → 구현 → 문서 동기화"라는 동일한 흐름을 매번 거치게 된다는 것을 깨닫게 됩니다. 이 일련의 워크플로우를 11개의 skill로 묶어, plugin marketplace로서 모든 프로젝트에서 재사용할 수 있도록 만든 것이 이번에 소개할 workflow (dev-workflow)입니다.

여러 실제 프로젝트에서 검증된 방식을 "어떤 프로젝트에서도 동작하는" 형태로 일반화한 것이 포인트이며, 이 기사에서는 사용법 소개와 더불어 왜 이런 설계로 했는지(프로젝트 고유 정보를 어떻게 흡수하는지, 품질을 어떻게 담보하는지)까지 깊이 있게 다룹니다.

리포지토리는 여기 있습니다.

상정하는 독자

• Claude Code를 일상적으로 사용하며, 매번 같은 단계를 수동으로 수행하고 있는 분
• skill / plugin을 직접 제작하여 개발 플로우를 시스템화하고 싶은 분
• "AI에게 태스크를 통째로 맡기면 멋대로 스코프를 축소해 버리는" 문제로 고민하고 있는 분

전제 지식

• Claude Code의 기본 조작 (skill · slash command 개념)
• Git의 기본

애초에 무엇을 해결하는가

Claude Code의 skill은 편리하지만, 직접 만들다 보면 종종 프로젝트 고유의 사실(경로 · 커맨드 · 기술 스택 이름)을 skill 본문에 직접 작성(hard-coding) 하게 되어, 다른 프로젝트에서 재사용할 수 없게 됩니다.

workflow는 이 문제를 "skill 본문은 절차(how)만 가지고, 프로젝트 고유의 사실(what)은 실행 시점에 해결한다"는 설계로 회피합니다. 결과적으로, 한 번 도입하면 어떤 프로젝트에서도 그대로 동작하는 태스크 주도 개발(Task-driven development) 세트를 손에 넣을 수 있습니다.

skills 목록 (11종)

권장 사이클

기본 흐름은 이것뿐입니다.

/init-project # 최초 1회. 표준 구성을 생성 (→ stack-research를 체인 제안) 
↓
/understand-project # 매 세션. 파악 결과는 캐시됨
...

태스크는 task/진행중_{이름}.md로 만들어지며, 완료되면 git mv를 통해 task/완료_{이름}.md로 리네임됩니다. 태스크의 상태를 파일명으로 한눈에 알 수 있기 때문에, 중단 및 재개도 그대로 진행할 수 있습니다.

도입 방법

A. plugin marketplace (권장)

버전 관리 · 업데이트 배포 · 네임스페이스(dev-workflow:skill명)가 붙는 공식 공유 방식입니다.

# Claude Code의 세션 내에서 (어떤 프로젝트에서든 한 번만)
/plugin marketplace add Yuki-Maeda-valour/workflow
# 플러그인을 설치
...

리포지토리를 업데이트하면 /plugin marketplace update valour-workflow 명령으로 새 버전을 가져올 수 있습니다.

B. setup.sh (프로젝트 단위 복사 / symlink)

플러그인을 사용하지 않고, 대상 프로젝트의 .claude/skills/에 직접 배치하는 방식도 있습니다.

cd ~/dev/workflow
./setup.sh --link ~/dev/new-project # symlink (repo 업데이트가 즉시 반영됨)
./setup.sh --copy ~/dev/new-project # 복사 (프로젝트 측에서 독자적으로 수정할 경우)
...

여기서부터는 이 skills 모음을 "어떤 프로젝트에서도 동작하도록" 만들기 위한 설계의 핵심을 소개합니다. 단순한 사용법 이상으로, skill을 직접 만들고 싶은 분들에게 참고가 될 것입니다.

설계의 핵심 ①: 고유 정보의 3층 흡수 아키텍처 (3-Layer Absorption Architecture)

가장 중요한 원칙은 **"skill 본문은 절차(how)만 가지며, 프로젝트 고유의 사실(what)을 일절 하드코딩하지 않는다"**입니다. 사실 관계는 다음 3개 층에서 실행 시점에 해결됩니다.

예를 들어 패키지 매니저는 "package.json의 packageManager 필드 → lockfile → 기본 npm" 순으로 탐지하며, 품질 명령은 "profile → package.json의 scripts → 언어별 기본값" 순으로 해결합니다.

그리고 중요한 점은 project-profile.yml이 없어도 반드시 동작한다(모든 항목에 폴백(Fallback)이 있음)는 것입니다. 이것이 "어떤 프로젝트에 도입해도 즉시 동작하는" 범용성을 보장합니다. profile은 어디까지나 정밀도를 높이기 위한 선택적인 덮어쓰기 레이어(Overwrite Layer)라는 위치를 가집니다.

설계의 핵심 ②: 구현자와 검증자의 분리

AI에게 태스크를 맡기면, "일단 여기까지", "후속 태스크에서 대응"이라며 멋대로 스코프(Scope)를 축소하여 완료 보고를 해오는 문제가 있습니다. /do-task는 이를 구조적으로 방지합니다.

규모와 상관없이 구현은 implementer(서브 에이전트)에게 위임하고, team-lead는 항상 검증자 역할을 수행합니다.

• team-lead는 diff와 태스크 체크리스트를 기계적으로 대조합니다 (grep -cE '^\s*- \[(x|X)\]'로 개수를 세어 diff와 일치하는지 확인).
• 단계적으로 실시|후속 태스크|이번에는 스코프 외|만 작성|다음 회 대응|일단과 같은 스코프 축소의 징후를 grep으로 탐지합니다.
• 완료 조건 명령은 team-lead가 직접 재실행합니다 (implementer의 자기 보고를 최종 확인으로 삼지 않음).

"구현한 본인에게 검증하게 하지 않는다"를 철저히 지킴으로써, 보고를 부풀리는 행위를 기계적으로 걸러내는 메커니즘입니다.

설계의 핵심 ③: 능력대가 다른 복수 모델을 통한 병렬 리뷰

태스크 리뷰는 실행 환경에서 이용 가능한 모델을 실행 시점에 확인하고, 능력 상위 모델 중 능력대가 다른 2~3개를 선정하여 병렬 리뷰를 수행하게 합니다.

여기서 흥미로운 점은 모델의 조합을 고정하지 않는다는 점입니다. fable + opus + sonnet처럼 버전을 하드코딩하지 않고, "실행 시점에 이용 가능한 상위 모델 중에서 선택한다"는 방식으로 작성함으로써 모델의 세대교체에 자동으로 대응합니다. Cursor 등 여러 벤더의 모델을 선택할 수 있는 환경이라면, 동일 벤더 내의 능력 차이보다 벤더를 넘나드는 다양성을 우선(Claude 최상위 + OpenAI 최상위 + ...)합니다.

또한, 리뷰 결과를 맹신하여 자동으로 반영하지 않는 것도 철저히 지켜지고 있습니다. team-lead가 각 지적 사항을 실제 코드로 확인(裏取り, verification)하고, valid / invalid / needs-user로 트리아지(triage)합니다. false positive(오탐)는 이유를 기록합니다. 동일한 지적이 2회 연속으로 남으면 사용자 확인, 5 라운드를 초과하면 토큰 비용 경고를 보내는 안전장치도 포함되어 있습니다.

설계의 핵심 ④: 환경에 따른 자동 축퇴 (Graceful Degradation)

서브 에이전트(sub-agent) 관련 기능은 환경에 따라 사용할 수 없는 경우가 있습니다. skill은 이용 가능한 도구를 확인하여 3단계로 자동 축퇴합니다(어느 단계에서 동작했는지는 반드시 보고합니다).

풀(Full) (Agent + SendMessage 가능): 실행 중인 에이전트에게 문의하거나 작업을 되돌리는(差し戻し, rollback/rework) 것이 가능
표준(Standard) (Agent만 가능): 위탁은 「기동 → 최종 리포트」의 단방향 방식. 되돌리기는 이전 결과물의 경로를 전달하는 신규 기동으로 대체
최소(Minimal) (서브 에이전트 기구 없음): 모든 공정을 직렬 실행. 다중 모델 리뷰는 관점을 전환한 셀프 리뷰(사실 정합성 → 계약 → 보안 → 규약)로 축퇴

「동작하는 환경을 선택하는」 것이 아니라 「어떤 환경에서도 축퇴하며 동작하는 것」을 우선하며, 사일런트 축퇴(silent degradation)는 금지(축퇴 시 이유를 명시)하도록 한 점이 실무적입니다.

문서와 캐시의 구분

결과물의 저장 위치 규칙도 명확하게 정해져 있습니다.

인간이나 다른 도구가 읽어야 할 지식은(요건, ADR, 운용, 지뢰 등. 정본) doc/

Claude Code의 동작 상태는(파악 캐시) .claude/

grasp.md (리뷰 로그 등. 휘발성)

.claude/ 하위의 캐시는 「① 없어도 모든 skill의 동작이 동일할 것 ② 정본에 없는 정보를 쌓지 않을 것 ③ gitignore 대상일 것」이라는 3가지 조건을 반드시 충족하도록 정해져 있습니다. 캐시는 어디까지나 재계산 비용을 절감할 뿐이며, 의존성을 만들지 않는다는 규율을 따릅니다.

영상에서도 말씀드렸습니다

감사하게도, あんテク(Anteku)님의 YouTube 채널에 초대받아 이 skills 모음에 대해 실제로 말씀드리는 시간을 가졌습니다. 함께 시청해 주시면 감사하겠습니다.

귀중한 기회를 주신 あんテク님께 이 자리를 빌려 진심으로 감사의 말씀을 드립니다.

요약

workflow (dev-workflow)는 Claude Code의 태스크 주도 개발을 skills화하여 모든 프로젝트에서 재사용하기 위한 plugin입니다. 설계의 핵심을 정리하면 다음과 같습니다.

3층 흡수: 고유 정보를 하드코딩하지 않고 profile → 동적 탐지 → CLAUDE.md로 해결. profile이 없어도 동작
구현자와 검증자의 분리: 스코프 축소를 기계적으로 탐지하며, 완료 조건은 검증자가 재실행
세대 추종형 다중 모델 리뷰: 모델을 고정하지 않고 실행 시점에 선택하며, 지적 사항은 확인 후 반영
자동 축퇴: 어떤 환경에서도 동작하며, 축퇴 시에는 반드시 명시

skill을 직접 제작하고 계신 분이라면, 특히 「고유 정보를 하드코딩하지 않는 3층 흡수」와 「구현자와 검증자의 분리」 이 두 가지만이라도 도입할 가치가 있다고 생각합니다. 자세한 설계는 docs/design.md에 정리되어 있으니, 관심이 있다면 살펴보시기 바랍니다.

Discussion