티켓 1장부터 설계를 진행하는 AI 오케스트레이터를 육성한 이야기 ②실전편: SKILL.md 전문과 사용법
요약
Claude Code를 활용하여 티켓 기반의 설계 오케스트레이터인 'feature-design-flow'를 구축한 실전 사례를 소개합니다. SKILL.md를 본체로 하고 참조 파일을 분리한 구조를 통해 설계 공정의 10단계를 자동화하고 품질 게이트를 관리하는 방법을 다룹니다.
핵심 포인트
- SKILL.md와 참조 파일로 분리된 모듈형 오케스트레이터 구조
- 사용자 확인을 거치는 대화형 10단계 설계 공정 구축
- 품질 확보를 위한 단계별 품질 게이트(Scope 확정, 설계 리뷰) 삽입
- 티켓 분할 및 DB 조사 규칙 등 구체적인 참조 가이드 활용
이 기사는 Claude Code용으로 만든 설계 오케스트레이터 feature-design-flow의 **실물(프롬프트 전문)**을 공개하고, 어떻게 읽어야 하는지, 자신의 팀에 맞춰 어디를 변경해야 하는지를 정리한 것입니다.
왜 이것을 만들었는지, 어떤 실패를 거쳐 품질 게이트(Quality Gate)를 사후에 추가해 나갔는지와 같은 사상 및 경위는 별도의 기사에 작성되어 있습니다. 배경을 알고 싶은 분은 먼저 그 글을 읽어주시기 바랍니다.
이하 내용은 모두 외부 공개를 위해 익명화 및 일반화되었습니다. 고유한 리포지토리(Repository) 이름, 테이블 이름, 티켓 번호 등은 숨겼지만, 단계별로 "사용자의 확인을 받기 전까지 진행하지 않음"이라는 제어나 "완료 조건"을 구축한 방식은 그대로 읽어내실 수 있을 것입니다.
파일 구성 지도
feature-design-flow는 "얇은 본체(SKILL.md) + 두꺼운 참조 파일군(references/)"이라는 구성입니다. 본체는 공정의 진행만을 담당하며, 판단 규칙이나 템플릿은 참조 파일로 외부에 분리해 두었습니다. 개선할 때는 본체가 아니라 해당 참조 파일을 수정하는 것만으로 충분합니다.
또한, 이 스킬은 단독으로 완결되는 것이 아니라, 설계 주변의 다른 스킬(요구사항 리뷰, 견적, QA, 재발 방지 관점을 축적하는 학습계 스킬)과 연계되는 핵심으로서 동작합니다. 그 전체상은 사상편에서 다루었으므로, 본 기사에서는 feature-design-flow 단독의 전문에 집중합니다.
| 파일 | 역할 (무엇을 하는가) |
|---|---|
SKILL.md | 본체. 시작 티켓 1장에서 견적까지의 10단계를 정의하고, 각 단계에서 참조 파일을 호출하는 오케스트레이터 |
references/investigation-rules.md | 차분(Diff) 정리의 4가지 관점과 티켓 종류별 관점 전환. "코드 뒷받침 원칙(단계 이월 금지)"도 여기에 포함 |
references/db-investigation-rules.md | DB 조사가 필요할 때의 도구, 절차, 주의사항. 접속할 수 없는 환경에서의 대안(스키마 문서 참조)도 포함 |
references/design-review-checklist.md | 기본 설계 리뷰 관점. 1. 문서 정합성 리뷰와 2. 설계 타당성 리뷰(6축)의 두 가지 구성 |
references/basic-design-template.md | 기본 설계의 장 구성. 변경 내용의 정본(변경 사항 목록)을 중심으로 한 집필 순서 및 완료 조건 |
references/detail-design-template.md | 상세 설계의 장 구성. 기본 설계와의 "경계표"를 통해 중복 기술을 방지 |
references/ticket-split-rules.md | 구현 티켓의 분할 판단(2/3/4분할) 및 DB 변경을 독립 티켓으로 분리하는 원칙 |
references/implementation-ticket-template.md | 구현 티켓의 description 템플릿 |
references/review-ticket-template.md | 리뷰 티켓의 description 템플릿 |
스킬이 진행하는 10단계 (완성형)
전문을 읽기 전에, 이 스킬이 결국 어떤 공정을 어떤 순서로 진행하는지 개관해 두겠습니다. 시작 티켓의 키를 하나 전달하면, 대화식으로 다음 10단계가 진행되며, 각 단계에서 사용자의 확인을 받은 후 다음으로 넘어갑니다.
사상편에서는 품질 게이트를 추가하기 전의 "순수 8단계"를 소개했습니다. 아래는 거기에 운영 과정에서 추가해 나간 게이트(Step 3.5 스코프 확정 및 Step 4-2.5 설계 타당성 리뷰)까지 삽입한 완성형입니다. 주황색으로 표시된 두 가지가 나중에 추가한 품질 게이트에 해당합니다.
- 기점 티켓 취득 및 종별 판별 (起点チケット取得・種別判別) — 종별에 따라 이후의 조사 관점을 전환한다. 자식 티켓(Sub-ticket)의 기표처도 여기서 미리 확인한다. -
- 현상 조사 (코드 + 필요에 따라 DB) (現状調査（コード＋必要に応じてDB）) — 관련 서비스, 모델, 화면, 정의를 횡단 조사한다. 코드로 뒷받침(Back-up)할 수 있다는 전제는 여기서 확정한다. -
- 차이 정리 (4관점) (差分整理（4観点）) — 기술적 차이 / 운용 전제·업무적 의도 / 영향 범위 / 판단 방향성,의 4개 축으로 구조화한다. -
- (3.5) 스코프 조기 확정 게이트 ((3.5)スコープ早期確定ゲート) — 「대상 화면 / 대상 테이블 / 스코프 외」의 3가지 리스트를 확정한다. 전 단계에서 모든 쓰기 경로를 기계적으로 열거한다. -
- 기본 설계 (基本設計) — 변경 내용의 정본(正本)은 「변경 개소 목록」 장에 집약하고, 요약이나 각 사양 장은 거기서부터 기계적으로 작성한다. -
- (4-2.5) 6축 설계 타당성 리뷰 ((4-2.5)6軸の設計妥当性レビュー) — 문서 정합성 체크에 더해, 설계의 근본 전제를 6개 축으로 점검한다. -
- 구현 티켓 분할 제안 (実装チケット分割提案) — 담당 인원, 병행 작업성, PR(Pull Request) 사이즈, 테스트 책임, 릴리스 순서를 판단 축으로 하여 2~4개로 분할 제안을 한다. -
- 상세 설계 (분할 단위별) (詳細設計（分割単位ごと）) — 메서드 시그니처(Method Signature), SQL 최종 형태, 구형 $\rightarrow$ 신형 매핑 등, 구현으로 옮길 수 있는 입도(Granularity)까지 구체화한다. -
- 자식 티켓 기표 (子チケット起票) — 설계 / 구현 / 리뷰 / QA 테스트 티켓을 명명 규칙에 따라 기표한다. -
- 견적 연계 $\rightarrow$ 예정 시간 반영 (見積もり連携 $\rightarrow$ 予定時間反映) — 견적 스킬을 호출하여, 결과를 각 티켓의 예정 시간에 반영한다.
이 10단계가 SKILL.md의 「전체 플로우」로서 그대로 작성되어 있습니다. 다음은 각 파일의 전문입니다. 내용이 길므로 필요한 부분만 열어서 읽어주세요.
전문을 읽기 전에: 파악해 두어야 할 3가지 기술
전문을 갑자기 처음부터 읽기보다, 먼저 "이 스킬의 핵심은 어디인가"를 알고 있으면 각 파일이 무엇을 위해 그렇게 작성되었는지 추적하기 쉬워집니다. 설계 의도가 가장 잘 드러나 있는 곳은 다음 세 군데입니다.
1. 각 단계에 "사용자 확인을 받기 전까지 진행하지 않음"을 심어두었다. SKILL.md 도입부의 「중요 원칙」에 "각 단계에서 반드시 사용자 확인을 받는다. 마음대로 다음 단계로 진행하지 않는다"라고 명시하였으며, 나아가 Step 1(자식 티켓 기표처 사전 확인), Step 2-1(조사 브랜치 확인), 각 Step 말미의 「완료 조건(플로우의 게이트)」을 통해, 확인 및 합의를 얻기 전까지 다음 공정으로 넘어가지 못하게 하는 구조로 만들었습니다. AI에게 전적으로 맡기지 않고, 중요한 지점에서 인간이 승인하도록 하는 설계가 본체 곳곳에 흩어져 있음을 알 수 있을 것입니다.
2. "변경 개소 목록을 정본으로 한다"는 집필 순서를 강제하고 있다. SKILL.md의 Step 4-1 「집필 순서와 볼륨 축소 규칙」과 references/basic-design-template.md의 완료 조건이 이 역할을 담당합니다. 구체적인 값(enum 명, 경로, 마스터 값)은 변경 개소 목록 장에만 쓰고, 요약이나 각 사양 장은 거기서부터 기계적으로 작성하도록—즉, 순서를 프롬프트로 제약함으로써—AI가 장마다 모순되거나, 같은 내용을 중복해서 써서 문서가 불필요하게 비대해지는 것을 방지하고 있습니다.
3. "구현 시 확인"을 완료 조건에서 금지하고 있다. references/investigation-rules.md의 「코드 뒷받침 원칙 (페이즈 이월 금지)」과 각 템플릿의 완료 조건에 있는 「다음 페이즈로 미루는 표현을 본문에 남기지 않는다」가 이것입니다. 코드를 보면 몇 분 안에 알 수 있는 전제를 "구현 시 확인"이라고 적어 미루는 행위를 명시적으로 금지하고 있습니다. 이와 함께 "구현하며 직접 움직여봐야 비로소 알 수 있는 것"은 이월 가능하다고 선을 그어 두었습니다.
이 세 가지를 머릿속에 넣고 읽으면, 이후의 전문이 "단순한 절차서"가 아니라 특정 실패를 방지하기 위해 설계된 장치들의 집합체로 보일 것입니다.
SKILL.md
---
name: feature-design-flow
description: Backlog의 기점 티켓(PBI / 요청 / 버그 / 설계 태스크 / 리팩토링 등)으로부터, 현상 코드 조사 $\rightarrow$ 4관점 차이 정리 $\rightarrow$ 기본 설계 $\rightarrow$ 상세 설계 $\rightarrow$ 자식 티켓 기표 $\rightarrow$ /estimate 연계 $\rightarrow$ 예정 시간 반영까지 일관되게 대화형으로 진행하는 오케스트레이터. "PBI-XXX로 설계를 진행해", "DEV-XXXX를 분해해", "○○를 견적까지 진행해", "기능 설계 플로우를 수행해" 등으로 기동. Backlog 기점의 기능 구현 계획을 세울 때는 적극적으로 사용할 것.
...
references/basic-design-template.md
# 기본 설계 템플릿 (basic-design-template.md)
구현 직전의 메서드 시그니처(Method Signature)·SQL은 생략하고, 요구사항 (What/Why) → 사양 (How) → 변경 사항 (Where)의 계층으로 기술한다. 기획자나 PM이 읽어도 이해할 수 있는 수준이어야 한다.
**변경 내용의 정본은 §10 변경 사항 목록** (종별 + 현상 ⇄ 신규 사양 + 이유)이다. §1.5 변경점 요약과 §3~§6은 §10에서 발췌·요약하며, 동일한 구체적 값(enum 명, 마스터 Value, 파일 경로)을 중복해서 작성하지 않는다. 독자는 §1.5 요약 → 상세 장 순서로 "어디를·왜 바꿨는지"를 파악할 수 있다. 메서드 시그니처·SQL 최종 형태·구(舊)→신(新) 매핑 전건은 본서에서 다루지 않고 상세 설계(detail-design-template.md의 경계표 참조)에 맡긴다.
...
references/investigation-rules.md
# 차분 정리 규칙 (4가지 관점)
CLAUDE.md의 「조사 보고의 품질」에 기반하여, 다음 4가지 관점으로 차분(Difference)을 정리한다. 단순히 차분을 나열하는 데 그치지 않고, 업무 영향·운영 전제·판단 방향까지 깊이 있게 다룬다.
## 1. 무엇이 다른가 (기술적 차분)
...
references/db-investigation-rules.md
# DB 조사 규칙
스킬 `feature-design-flow`의 Step 2 「현상 조사」 내에서 DB를 확인하는 경우의 가이드.
---
...
references/design-review-checklist.md
# 기본 설계 리뷰 체크리스트
기본 설계를 사용자에게 제시하기 전에, 2종류의 리뷰를 순차적으로 수행한다. 두 리뷰는 목적이 다르므로 나누어 실시한다.
| 리뷰 | 사용하는 Step | 확인 대상 | 한 줄 요약 |
...
references/detail-design-template.md
# 상세 설계 템플릿
구현에 그대로 옮길 수 있는 수준으로, 변경 대상 파일·구(舊)→신(新) 매핑·신규 정의의 속성·필요한 SQL을 구체화한다.
## 기본 설계 (§10)와의 경계표
...
references/ticket-split-rules.md
# 티켓 분할 규칙
## 판단 축
1. **담당자 인원수**: 1명이라면 2~3분할, 복수로 병행한다면 4분할 이상도 검토
...
references/implementation-ticket-template.md
# 구현 티켓 description 템플릿
Backlog의 add_issue / update_issue에서 사용하는 description 템플릿. 프로젝트의 기본 템플릿 (## 목적 / ## 대응 내용 / ## 완료 조건 / ## 서브 태스크 등)을 따른다.
...
references/review-ticket-template.md
# 리뷰 티켓 description 템플릿
리뷰어가 구현자와 다를 경우에 작성하는, 종별 「리뷰」 티켓용 템플릿.
---
...
자신의 팀에 맞춰 커스터마이징한다면
이 스킬은 우리 팀(Blazor + Backlog + SQL Server)의 상황에 맞춰 만들어져 있습니다. 그대로 사용하기보다는, 아래 내용들을 자신의 환경에 맞춰 교체하는 것이 현실적입니다. 효과가 클 것으로 예상되는 순서대로 나열합니다.
1. 티켓 관리 도구 (Backlog 이외를 사용하는 경우)
SKILL.md의 단계는 Backlog의 MCP (mcp__backlog__*)를 전제로 하고 있습니다. Jira, GitHub Issues, Notion 등으로 바꾼다면, 티켓 취득·기표·갱신 관련 도구 호출과 references/implementation-ticket-template.md / review-ticket-template.md의 description 템플릿을 해당 도구의 항목명·명명 규칙에 맞춰 다시 작성해야 합니다. 10단계의 골격(조사 → 차분 정리 → 설계 → 분할 → 기표 → 견적)은 도구에 의존하지 않으므로 이 부분은 유용하게 사용할 수 있습니다.
2. 기술 스택 · 리포지토리 구성
SKILL.md의 조사 대상 경로 (Services/, Repositories/, Models.Entities/ 등)나 references/db-investigation-rules.md...
DB 전제 조건(SQL Server)은 저희의 구성과 동일합니다. 본인의 레이어 구성, 언어, DB에 맞춰 조사 대상의 위치와 근거 확인 방법(.csproj 등 의존성 정의 파일 등)을 교체해 주세요.
3. 설계 템플릿의 목차 구성
references/basic-design-template.md / detail-design-template.md는 저희의 리뷰 과정에서 필요해진 장(Chapter)들로 구성되어 있습니다. 팀의 설계서 포맷이 있다면 그 목차에 맞춰도 무방합니다. 다만, "변경 내용의 정본(Single Source of Truth)을 하나로 정하고, 요약이나 각 장은 거기서부터 기계적으로 파생시킨다(이중 기술하지 않는다)"라는 집필 순서의 원칙만큼은 지키는 것이 내용의 비대화와 모순을 방지하는 데 도움이 됩니다.
4. 리뷰 관점
references/design-review-checklist.md의 6개 축은 ISO/IEC/IEEE 29148 등을 토대로 하고 있지만, 팀에서 중시하는 관점(보안, 성능, 특정 도메인의 제약 등)이 있다면 추가해 주세요. 고정된 체크리스트로 만들지 않고 "관점만 정의하고 구체적인 내용은 그때마다 생성하게 한다"는 방침으로 두면 유지보수가 훨씬 수월합니다.
5. 견적 및 티켓 입도(Granularity)
SKILL.md의 견적 연계(Step 9) 고정 설정이나, references/ticket-split-rules.md의 분할 기준(PR 사이즈 500행, 담당 인원수에 따른 2~4분할 등)은 팀의 체제에 따라 다릅니다. 리뷰 체제 및 병행 작업 여부에 맞춰 숫자를 조정해 주세요.
운용하며 알게 된 주의사항 (ハマりどころ)
도입하여 실제로 돌려보면 설계 내용과는 별개의 부분에서 막히게 됩니다. 미리 알고 있으면 편한 함정들을 나열해 두겠습니다.
장시간 세션에서 도구 호출(Tool Call) 파싱(Parse) 실패. 대화가 여러 단계로 이어지면, 내부의 도구 실행 JSON이 중간에 끊겨 형식이 잘못되거나(Malformed), 합의된 스코프(Scope)를 놓치게 됩니다. 원인은 두 가지이며 대처법도 다릅니다. 하나는 컨텍스트(Context)의 비대화입니다. 무거운 코드 조사, DB 조사, PR diff 취득 작업은 서브 에이전트(Sub-agent)에게 넘기고, 결론 요약만 받도록 하면 효과적입니다. 작성 직후의 설계서를 다시 읽지 않게 하거나, 티켓 취득 및 업데이트를 반복하지 않게 하는 것도 은근히 효과가 있습니다. 다른 하나는 1회 응답당 출력 길이입니다. 방대한 본문을 포함하는 티켓 생성은 1턴에 1건씩 순차적으로 실행하고, 생성물의 전문을 채팅창에 다시 게시하지 않도록 제어함으로써 방지할 수 있습니다. SKILL.md 서두의 "중요 원칙"에 이 두 가지 계통을 나누어 적어 두었습니다. 그럼에도 막혔을 때의 마지막 수단은 /compact입니다. 대화 이력을 요약하여 압축해 주므로, 긴 세션이 무거워졌을 때 한 번 실행하면 복구할 수 있습니다.
MCP가 없는 환경에서 DB 조사가 중단됨. DB 영향 판단은 생략하지 않는 방침이므로, DB에 접속할 수 없으면 진행이 어려워집니다. references/db-investigation-rules.md에는 접속할 수 없는 환경에서는 스키마 문서(Schema Document)를 참조하여 영향 유무 판단까지는 수행한다는 대체 방안을 적어 두었습니다. 이를 "환경이 없으니 나중에"라고 미루게 되면 결국 페이즈(Phase)가 다음으로 넘어가는 문제가 재발하므로, 판단만큼은 해당 페이즈에서 끝내는 것을 추천합니다.
갑자기 10단계를 전부 돌리지 않는 것이 좋다. 익숙해지기 전까지는 우선 기본 설계(Step 4)까지 돌리고 멈춘 뒤, 설계의 품질을 확인하고 다음으로 진행하는 것이 안전합니다. 처음부터 견적 및 티켓 생성까지 한꺼번에 실행하면, 중간의 전제 조건 불일치가 마지막까지 파급되어 한꺼번에 재작업(Retake)이 발생하게 됩니다. 각 단계에서 확인을 받도록 설계한 이유는 이러한 중간 정지를 자연스럽게 수행하기 위함이기도 합니다.
하위 티켓의 생성처는 처음에 결정한다. 티켓 생성 직전에 "어떤 상위 티켓에 매달 것인가"를 확인하면 설계 내용을 다시 구성해야 하는 재작업이 발생합니다. SKILL.md는 Step 1 시점에 생성처를 확인하도록 만들어져 있습니다. 본인의 티켓 운용 방식에 맞춰 이 확인 내용을 초기에 조정해 두는 것이 좋습니다.
Discussion
AI 자동 생성 콘텐츠
본 콘텐츠는 Zenn AI의 원문을 AI가 자동으로 요약·번역·분석한 것입니다. 원 저작권은 원저작자에게 있으며, 정확한 내용은 반드시 원문을 확인해 주세요.
원문 바로가기