서론

약 반년 전부터 자신만의 플랜 모드(Plan Mode) 및 구현 모드(Implementation Mode)를 위한 스킬을 만들어 운용하고 있는데, 개인적으로 상당히 괜찮은 느낌으로 구현되었습니다.

원래 제작하려고 생각한 계기는, Kiro의 Spec 모드를 사용했을 때 구현 계획과 태스크(Task) md 파일을 생성하는 것이 흥미롭다고 느꼈고, Claude Code에서도 이와 유사한 파일을 생성하며 구현을 진행하고 싶었기 때문입니다.

플랜 모드의 한계

Claude Code의 표준 플랜 모드는 기본적으로 Ask 도구를 통한 상호작용 결과가 md 파일 하나에 작성됩니다. 하지만 운용하는 과정에서 다음과 같은 불편함을 느끼게 되었습니다.

• 탐색 결과나 사용자에게 질문한 내용 등을 독립된 파일로 남길 수 없음
• 출력 대상이 md로 고정되어 있어, 기술적인 해설을 HTML로 만들게 하는 등의 응용이 어려움

그래서 구현 계획·태스크에 더해 테스트 케이스나 기술 해설 등도 생성할 수 있고, 나만의 포맷을 강제할 수 있는 스킬을 만들기로 했습니다. 목적은 다음 세 가지입니다.

• 구현 시의 인지 부하를 낮춤
• 테스트 케이스의 누락을 줄임
• 구현 계획을 철저하게 다듬음

만든 스킬의 전체 모습

크게 다음과 같은 두 가지 스킬을 조합하여 사용하고 있습니다.

• 플랜 모드 스킬: 탐색·요건 정리·구현 계획 및 태스크로의 구체화까지 수행
• 구현 모드 스킬: 플랜 모드에서 작성한 결과물을 바탕으로 구현을 진행

플랜 모드에서 작성한 파일은 계획마다 폴더로 묶고, 폴더명에 인덱스(연번)를 부여합니다. 구현 모드는 이 인덱스를 인자로 받으며, 생략 시에는 최신 것을 대상으로 합니다.

출력되는 폴더 구성의 이미지는 다음과 같습니다.

.plugin-workspace/.specs/001-feature-name/
├── PLANNING # 페이즈 마커 (존재하는 동안은 계획 중)
├── requirements.md # 요건
...

고안한 점

이 스킬에는 나름대로 몇 가지 고안한 점이 있습니다.

1. 출력을 분할하는 설계

표준 플랜 모드처럼 하나의 md에 모든 것을 채워 넣는 것이 아니라, 페이즈(Phase)나 용도에 따라 파일을 나누어 출력하는 구성으로 했습니다. 요건·설계·태스크·조사 메모를 각각 별도의 파일로 분리해 두는 심플한 방침입니다.

분할해 두면 다음과 같은 이점이 있습니다.

• 결과물마다 출력 형식을 바꿀 수 있음 (테스트 케이스는 HTML, 구현 계획은 md와 같이 구분하여 사용 가능)
• 특정 목적에 맞는 파일만 열어서 확인할 수 있음
• 특정 페이즈만 나중에 교체할 수 있음
• PLANNING 파일의 유무를 페이즈 마커로 사용할 수 있어, 후술할 가드(Guard) 처리나 자동 아카이브와 연동하기 쉬움

요컨대, md 한 장에 모두 담았을 때는 어려웠던 '페이즈 단위의 취급'을 파일 분할을 통해 성립시킨 것이 포인트입니다.

2. 출력 형식을 설정 파일로 전환

용도에 따라 md가 아닌 HTML로 기술 해설을 내보내고 싶은 경우가 있습니다. 그래서 스킬 측에 하드코딩하지 않고, 설정 파일로 출력 형식을 전환할 수 있도록 했습니다.

.plugin-workspace/.specs/.config.yml과 같은 파일에 결과물별 출력 형식을 적어 두는 이미지입니다.

output-formats:
  implementation-plan: md
  design-doc: md
...

스킬 기동 시 이 설정을 읽어 .md를 만들지 .html을 만들지 분기합니다. 플랜 기동 시마다 프롬프트로 "이것은 HTML로"라고 다시 지시할 필요가 없으므로, 반복해서 사용할 때의 재현성이 높아졌습니다.

설정은 프로젝트마다 가질 수 있으므로, "이 프로젝트는 전부 md로 해도 된다", "여기는 기술 해설만 HTML로 하고 싶다"와 같은 구분도 가능합니다.

3. Hooks를 통한 가드

플랜 모드 중에 소스 코드 등의 파일을 멋대로 수정하면 곤란하므로, Claude Code의 Hooks를 사용하여 가드를 걸고 있습니다.

Claude Code의 Hooks에서는 현재 세션 ID를 포함한 정보가 JSON으로 전달되므로, 이를 이용하여 "이 세션은 지금 계획 모드 중이다"라는 상태를 파일로 표현합니다.

구체적으로는, 스킬(skill) 기동 시 세션 ID와 동일한 이름의 가드(guard) 파일을 생성합니다.

.plugin-workspace/.specs/.guard/{SESSION_ID}

이 파일이 존재하는 동안에는 PreToolUse 훅(hook)에서 Write / Edit / MultiEdit / Bash를 차단하는 단순한 메커니즘입니다.

가드 스크립트의 내용

셸 스크립트(shell script) 측에서는 표준 입력(stdin)으로 전달되는 JSON에서 세션 ID와 툴(tool) 이름을 추출하고, 대응하는 가드 파일의 존재 여부에 따라 동작을 전환합니다. exit 2를 반환하면 툴 실행이 차단되며, 표준 에러 출력(stderr)의 내용이 모델에 대한 피드백으로 전달됩니다.

INPUT=$(cat)
SESSION_ID=$(echo "$INPUT" | jq -r '.session_id // empty')
TOOL=$(echo "$INPUT" | jq -r '.tool_name // empty')
...

Bash 툴에 대해서도 마찬가지로, 리다이렉션(> / >>)이나 tee / sed -i / cp / mv / rm / mkdir과 같은 쓰기 계열 명령어를 패턴 매칭으로 포착하여 차단하고 있습니다. .plugin-workspace/.specs/ 하위로의 조작만은 예외적으로 허용함으로써, 계획 파일의 생성 및 업데이트는 그대로 수행할 수 있도록 했습니다.

가드 해제

가드 파일은 세션 ID별로 생성되므로, /clear를 하여 다른 세션에서 구현 모드를 기동하면 해당 세션에는 가드가 걸리지 않습니다. 저의 경우 계획이 끝나면 한 번 /clear를 한 뒤 구현 모드로 들어가는 경우가 많기 때문에, 실질적으로 이것이 해제 절차가 됩니다. 물론 가드 파일을 수동으로 삭제해도 해제할 수 있습니다.

모델 측에서 rm으로 가드 파일을 지우려고 시도하는 경우에는 Bash 훅 측에서 이를 감지하여 차단합니다. 이는 동일한 세션 내에서 멋대로 구현 단계로 이행해 버리는 것을 방지하기 위함입니다.

4. Hooks로 세션 이름을 자동 리네임하기

여러 개의 spec을 병행하여 돌리다 보면, Claude Code의 세션 목록을 보았을 때 "어느 것이 어떤 spec의 어느 단계인지" 알 수 없게 되기 쉽습니다.

이 또한 Hooks로 해결하고 있으며, UserPromptSubmit 훅에서 현재 다루고 있는 spec 이름과 단계를 조합한 세션 타이틀을 자동으로 부여하도록 했습니다.

UserPromptSubmit은 훅의 표준 출력(stdout)에 hookSpecificOutput.sessionTitle을 포함한 JSON을 반환하면, Claude Code 측에서 해당 값을 세션 타이틀로 사용합니다. 다음과 같은 훅으로 타이틀을 구성하고 있습니다.

PROMPT=$(echo "$INPUT" | jq -r '.prompt // empty')
case "$PROMPT" in
/spec-driven-dev*) LABEL="📋 plan" ;;
...

이렇게 하면 "📋 plan #003", "🔨 impl #002"와 같은 타이틀이 자동으로 나열됩니다. 개인적으로 가장 유용한 점은 여러 세션을 동시에 구동하고 있을 때, 어떤 것이 계획 모드이고 어떤 것이 구현 모드인지 한눈에 알 수 있다는 점입니다.

5. 요구사항 미확정 사항이 남아있는 동안 계획 진행 차단하기

요구사항이 완전히 결정되지 않은 상태에서 계획 작성을 시작하지 않도록, 여기에도 차단 장치를 마련했습니다.

구체적으로는 구현 계획에 들어가기 전 단계로서 requirements.md 안에 "미결 확인 사항" 체크박스(□)를 두어, 이것이 남아있는 상태에서 implementation-plan.md를 작성하려고 하면 훅 측에서 차단하는 메커니즘입니다.

체크 흐름은 단순합니다. implementation-plan에 대한 Write / Edit 요청이 왔을 때만 작동하며, 동일한 폴더의 requirements.md 내 해당 섹션을 확인합니다.

case "$FILE" in
*implementation-plan*) ;;
*) exit 0 ;;
...

6. Stop 훅으로 완료된 spec을 자동 아카이브하기

세션 종료 시, Stop 훅 (Hook)을 통해 .plugin-workspace/.specs/ 내부를 탐색하여, PLANNING 파일이 남아있지 않은 spec 폴더를 archive/ 하위로 자동 이동하도록 설정했습니다.

for dir in .plugin-workspace/.specs/[0-9][0-9][0-9]-*/; do
[ -d "$dir" ] || continue
[ -f "${dir}PLANNING" ] && continue # 아직 계획 중이면 스킵
...

"PLANNING을 삭제함 = 구현 완료"라는 판정 기준입니다. 수동으로 하면 반드시 게을러지기 쉬운 아카이브 작업을 자동으로 처리할 수 있어, 워크스페이스를 항상 깨끗한 상태로 유지할 수 있습니다.

요약

이 스킬의 본질은 자신만의 출력 형식이나 규칙을 스킬 (Skill)과 훅 (Hooks)으로 강제할 수 있다는 점입니다. 플랜 모드 자체를 AI에게 맡기는 것이 아니라, "어떤 파일에 어떤 입도 (Granularity)로 출력할 것인가", "언제 구현을 허가할 것인가"와 같은 운영 규칙을 직접 설계할 수 있다는 점이 마음에 듭니다.

참고

Discussion