개요
writing-plans 스킬이 하는 일
writing-plans 스킬은 제품 스펙이나 기술 요구사항 문서를, 아직 아무도 코드를 건드리기 전 단계에서 완전하고 구현 가능한 플랜으로 바꿔 줍니다. 여러 단계로 이루어진 기능이나 변경 사항을 릴리스해야 하고, 사전 맥락 없이도 다른 엔지니어가 따라갈 수 있는 명확하고 잘 쪼개진 플랜이 필요할 때를 위해 설계되었습니다.
writing-plans를 사용하면 다음과 같은 플랜을 만들 수 있습니다:
- 구현자가 유능한 개발자이지만 당신의 코드베이스와 도메인에는 익숙하지 않다고 가정합니다.
- 작업 각 부분마다 어떤 파일을 새로 만들거나 수정해야 하는지를 구체적으로 명시합니다.
- 필요한 테스트, 문서 업데이트, 수동 확인 작업을 빠짐없이 짚어줍니다.
- 작업을 경계가 분명한 작고, 배포 가능한 태스크들로 쪼갭니다.
이렇게 하면 작업을 다른 사람에게 넘기거나 플랜을 리뷰하기가 쉬워지고, 스코프가 커지거나 숨은 엣지 케이스가 생기는 것을 막을 수 있습니다. DRY, YAGNI, TDD, 잦은 커밋 같은 관행을 반영하지만, 초점은 코드 생성이 아니라 프로젝트 계획 수립과 작업 분해에 맞춰져 있습니다.
writing-plans는 누가 사용하면 좋을까요?
다음과 같은 경우 writing-plans 스킬을 사용하는 것이 좋습니다:
- 기능 개발과 리팩터링을 반복 가능한 방식으로 계획해야 하는 테크 리드와 엔지니어링 매니저.
- 리스크가 크거나 여러 영역에 걸친 변경을 구현하기 전에, 자신의 접근 방식을 먼저 명확히 정리하고 싶은 개발자 개인.
- 기여자 간 조율을 위해 명확한 서면 플랜이 필요한 subagent 기반 워크플로우나 분산 팀.
다음과 같은 상황에 특히 잘 맞습니다:
- 기능, 마이그레이션, 연동을 위한 스펙 또는 요구사항이 이미 있다.
- 작업이 여러 파일, 컴포넌트, 서비스에 걸쳐 있다.
- 다른 사람이 계속 질문하지 않고도 작업을 구현할 수 있게 하고 싶다.
반대로 다음과 같은 상황에는 잘 맞지 않습니다:
- 아직 문제나 해결책을 브레인스토밍 중이다 (먼저 아이데이션/브레인스토밍 스킬을 사용하세요).
- 작업이 매우 작아서 (예: 한 줄 수정) 정식 플랜이 필요 없다.
- 주된 목적이 코드 리뷰나 코드 생성이고, 플랜 수립이나 작업 분해가 아니다.
워크플로우에서의 위치
이 리포지토리는 writing-plans가 브레인스토밍 단계 이후에, 프로젝트용 전용 worktree에서 사용된다고 가정합니다. 일반적인 흐름은 다음과 같습니다:
- 스펙을 브레인스토밍하고 명확히 정리합니다(이 스킬 바깥에서 진행).
- 해당 기능을 위한 전용 worktree를 생성하거나 엽니다.
- writing-plans 스킬을 실행해 구현 플랜을 생성합니다.
- 기본적으로 플랜을 다음 경로에 저장합니다:
docs/superpowers/plans/YYYY-MM-DD-<feature-name>.md- 혹은 팀에서 정한 선호 플랜 경로.
- 구현 전에 플랜을 검증하기 위해, 제공된 템플릿을 사용해 plan document reviewer subagent를 선택적으로 호출합니다.
사용 방법
설치 및 설정
1. writing-plans 스킬 설치
obra/superpowers 리포지토리에서 스킬을 바로 설치할 수 있습니다:
npx skills add https://github.com/obra/superpowers --skill writing-plans
이 명령은 writing-plans 스킬 정의와 관련 프롬프트를 가져와, 자신의 프로젝트에서 사용할 수 있게 합니다.
2. 핵심 파일 살펴보기
설치 후 다음 주요 파일들을 검토해 워크플로우를 이해하고 팀에 맞게 조정하세요:
skills/writing-plans/SKILL.md– 스킬의 동작 방식, 범위, 플랜 구조, 엔지니어에 대한 가정을 설명하는 메인 문서입니다.skills/writing-plans/plan-document-reviewer-prompt.md– 완성된 플랜을 리뷰하는 subagent용 재사용 가능한 프롬프트 템플릿입니다.
리포지토리를 vendor 또는 mirror하는 방식에 따라 로컬 경로는 달라질 수 있지만, 파일 이름은 동일합니다.
writing-plans 실행 준비
3. 스펙과 스코프 확인
writing-plans를 사용하기 전에 다음을 준비했는지 확인하세요:
- 해당 기능이나 변경에 대한 명확한 스펙 또는 요구사항 문서.
- 주요 컴포넌트, 연동, 제약 조건을 식별할 수 있을 정도의 상세도.
이 스킬에는 Scope Check 단계가 포함되어 있습니다. 스펙이 서로 독립적인 여러 서브시스템을 다루고 있다면, 브레인스토밍 단계에서 이미 별도의 서브 프로젝트 스펙으로 나누어졌다고 가정합니다. 그렇지 않았다면 다음과 같이 진행해야 합니다:
- 작업을 서브시스템별로 별도 플랜으로 나눕니다.
- 각 플랜이 단독으로 동작 가능하고 테스트 가능한 소프트웨어를 만들어낼 수 있도록 합니다.
이렇게 하면 하나의 플랜이 감당하기 어려울 만큼 커지는 것을 막고, 배포 단위와 작업 범위를 자연스럽게 맞출 수 있습니다.
4. worktree와 플랜 파일 준비
upstream 가이드는 다음과 같은 상태를 가정합니다:
-
해당 기능을 위한 전용 worktree에서 작업한다(브레인스토밍 중에 설정).
-
생성된 구현 플랜을 다음 경로에 저장한다:
docs/superpowers/plans/YYYY-MM-DD-<feature-name>.md
팀에서 docs/plans/나 planning/ 등 다른 디렉터리 구조를 선호한다면 이 위치를 바꿔도 됩니다. 중요한 점은 플랜이 버전 관리에 포함되어 코드와 함께 버전이 기록되고, 나중에 찾기 쉽도록 관리된다는 것입니다.
스킬 실행과 플랜 작성
5. 플래닝 세션 알리고 시작하기
스킬을 호출하거나 플래닝 대화를 시작할 때, 다음과 같이 명시적으로 선언하는 것이 좋습니다:
"I'm using the writing-plans skill to create the implementation plan."
이렇게 하면 지금의 목표가 구조화된 구현 플랜이지, 설계 탐색이나 코드 출력이 아니라는 점이 분명해집니다.
6. 먼저 파일 구조를 매핑하기
태스크를 나열하기 전에, writing-plans는 파일 단위 분해를 먼저 하도록 강조합니다:
- 어떤 파일을 새로 만들거나 수정할지를 식별합니다.
- 각 파일에 하나의 명확한 책임을 부여합니다.
- 인터페이스와 경계가 잘 정의된 단위로 설계합니다.
이 단계에서 플랜은 다음 질문에 답할 수 있어야 합니다:
- 새로운 로직은 어디에 위치하는가?
- 어떤 기존 파일이, 어떤 이유로 수정되는가?
- 이 파일들이 상위 수준에서 어떻게 상호작용하는가?
초기에 합리적인 파일 구조를 고정해 두면 작업 분해, 코드 리뷰, 이후 리팩터링이 훨씬 수월해집니다.
7. 작업을 작은 태스크로 쪼개기
파일 맵이 준비되면, writing-plans를 사용해 스펙을 작고, 각자 독립적으로 이해 가능한 태스크들의 시퀀스로 바꿉니다. upstream 가이드가 강조하는 점은 다음과 같습니다:
- 각 태스크는 명확한 목적을 가져야 하고, 실행 가능해야 합니다.
- 태스크는 잦은 커밋이 가능할 정도로 작아야 합니다.
- 플랜은 DRY(중복 지시 없음)해야 하며, YAGNI(불필요한 선제 작업 없음)를 지켜야 합니다.
각 태스크에는 다음 내용이 포함되어야 합니다:
- 어떤 파일이 영향을 받는지.
- 어떤 코드나 설정을 상위 수준에서 어떻게 변경해야 하는지.
- 추가하거나 수정해야 할 테스트.
- 업데이트해야 할 문서.
목표는 최소한의 맥락을 가진 엔지니어라도 개별 태스크 하나를 집어서 자신 있게 완료할 수 있게 만드는 것입니다.
8. 테스트와 문서를 플랜에 포함하기
writing-plans는 테스트와 문서 작업을 플랜 안에 직접 녹이는 것을 전제로 합니다:
- 추가하거나 업데이트해야 할 단위 테스트, 통합 테스트, E2E 테스트를 식별합니다.
- 필요한 경우 테스트 실행 방법(예: 명령어, 진입점)을 플랜에 명시합니다.
- README 섹션, 사용자 가이드, API 문서 등 필요한 문서 업데이트를 구체적으로 지정합니다.
이렇게 하면 품질과 유지보수성이 사후 작업이 아니라 플랜의 핵심 요소로 자리 잡습니다.
플랜 리뷰 및 개선
9. plan document reviewer 템플릿 사용하기(선택이지만 권장)
plan-document-reviewer-prompt.md 파일에는 plan document reviewer subagent를 위한 구조화된 프롬프트가 포함되어 있습니다. 이 subagent의 목적은 다음과 같습니다:
- 플랜이 완전한지, 스펙과 일치하는지 확인합니다.
- 작업 분해가 현실적이고 실행 가능하게 되어 있는지 검증합니다.
- 엔지니어가 플랜을 따라가며 막히지 않고 구현할 수 있는지 확인합니다.
템플릿에는 리뷰어가 점검해야 할 카테고리가 정리되어 있습니다. 예를 들어:
- 완결성(Completeness) – 중요한 요구사항에 대한 TODO, placeholder, 누락된 단계가 없는지.
- 스펙 정렬(Spec Alignment) – 플랜이 스펙을 커버하면서 불필요한 스코프 확장은 없는지.
- 작업 분해(Task Decomposition) – 태스크 경계가 명확하고 실제로 구현 가능하게 쪼개져 있는지.
- 구현 가능성(Buildability) – 유능한 엔지니어가 처음부터 끝까지 플랜만 보고 구현을 끝낼 수 있는지.
리뷰어는 문구 스타일 같은 사소한 문제보다는, 실제 구현에서 문제를 일으킬 이슈에 집중하도록 안내됩니다.
이 리뷰 단계는 CI, 코드 리뷰 워크플로우, 수동 리뷰 프로세스 등에 통합해 사용할 수 있습니다.
10. 피드백을 반영해 개선하기
리뷰어(사람이든 subagent든)가 요구사항 누락, 상충되는 단계, 지나치게 모호한 태스크 등을 발견했다면:
- 플랜 파일을 수정해 문제를 바로잡습니다.
- 필요하다면 리뷰를 다시 실행하거나 재요청합니다.
- 플랜이 승인되면, 구현을 위한 **단일 기준(source of truth)**으로 취급합니다.
팀에 맞는 writing-plans 활용
11. 구조와 규칙 커스터마이징하기
upstream 스킬은 기본 동작과 권장 사항을 명확히 정의하고 있지만, 다음과 같은 방식으로 팀에 맞게 조정할 수 있습니다:
- 리포지토리 레이아웃에 맞게 플랜 파일 위치를 변경합니다.
- 보안 리뷰, 성능 테스트 등 팀 고유의 체크리스트를 반복 태스크로 추가합니다.
- 플랜의 태스크를 티켓으로 매핑해 이슈 트래커와 연동합니다.
writing-plans는 본질적으로 구조화된 워크플로우와 프로젝트 관리에 관한 것이기 때문에, 언어·프레임워크·도메인이 달라져도 쉽게 적용할 수 있습니다.
자주 묻는 질문(FAQ)
writing-plans 스킬은 언제 사용해야 하나요?
여러 단계로 이루어진 기능, 리팩터링, 연동 작업에 대해 어느 정도 명확한 스펙이 있고, 사전 맥락이 없는 다른 엔지니어도 그대로 따라 구현할 수 있는 서면 구현 플랜이 필요할 때 writing-plans를 사용하세요. 특히 여러 파일이나 서브시스템을 건드리는 복잡한 변경 전에 효과적입니다.
어떤 경우에는 writing-plans가 맞지 않나요?
다음과 같은 경우 writing-plans는 적합하지 않습니다:
- 아직 해결책을 탐색 중이고 스펙이 불안정하다.
- 작업 규모가 너무 작아, 정식 플랜이 오히려 부담이 된다.
- 목표가 코드 생성이나 코드 리뷰이지, 작업 분해나 프로젝트 플래닝이 아니다.
이런 상황에서는 브레인스토밍, 설계, 코딩에 초점을 둔 다른 스킬을 사용하는 것이 좋습니다.
기본 docs/superpowers/plans/ 경로를 꼭 써야 하나요?
아니요. upstream 가이드는 플랜을 다음과 같이 저장할 것을 제안하지만:
docs/superpowers/plans/YYYY-MM-DD-<feature-name>.md
동시에 사용자가 선호하는 플랜 위치가 이 기본값보다 우선한다고 명시하고 있습니다. 리포지토리와 문서 표준에 맞는 디렉터리 구조나 네이밍 스킴이라면 어떤 방식이든 사용할 수 있습니다.
코드가 아닌 프로젝트에도 writing-plans를 사용할 수 있나요?
이 스킬은 파일 맵과 테스트 등을 포함한 소프트웨어 프로젝트와 코드베이스를 염두에 두고 작성되었습니다. 하지만 작업을 작은 태스크로 쪼개고, 책임을 매핑하며, 빠짐없이 체크한다는 핵심 아이디어는 다른 기술적 워크플로우에도 응용할 수 있습니다. 파일, 테스트, 문서 업데이트 개념이 어느 정도 있는 환경에서 가장 효과적입니다.
writing-plans는 온보딩이나 작업 인수인계에 어떻게 도움이 되나요?
writing-plans는 구현자가 당신의 코드베이스에 대한 사전 지식이 전혀 없고, 취향도 미덥지 않다는 가정을 바탕으로 하기에, 다음과 같은 행동을 유도합니다:
- 코드가 어디에 위치해야 하는지, 그 이유까지 설명합니다.
- 테스트와 문서를 명시적으로 드러냅니다.
- 태스크에서 애매함을 제거합니다.
덕분에 신규 팀원, 외주 인력, subagent에게 작업을 넘기기가 훨씬 쉬워집니다. 이들은 스펙만 보고 의도를 역추적할 필요 없이, 플랜 자체를 그대로 따라가면 됩니다.
writing-plans와 프로젝트 관리 도구는 어떤 관계인가요?
writing-plans는 프로젝트 관리 도구를 대체하기보다는 보완합니다:
- 스펙을 코드·파일 레벨에서 어떻게 구현할지 설명하는 구조화된 서면 플랜을 제공합니다.
- 그런 다음 플랜의 태스크를 Jira, GitHub Issues, Linear 같은 도구의 티켓으로 매핑할 수 있습니다.
이 스킬은 프로젝트 관리, 워크플로우 템플릿, 기술 보고서 작성의 교차 지점에 위치하며, 일관된 구현 플랜을 위한 재사용 가능한 패턴을 제공합니다.
전체 스킬 없이 reviewer 프롬프트만 따로 써도 되나요?
가능합니다. plan-document-reviewer-prompt.md 파일은 어떤 플랜 문서에도 적용할 수 있는 리뷰 템플릿으로 독립적으로 사용할 수 있습니다. subagent 프롬프트로 호출해 다음과 같이 활용할 수 있습니다:
- writing-plans로 작성한 플랜 리뷰.
- 다른 프로세스나 도구로 생성한 플랜 검토.
다만 플랜과 리뷰 모두가 writing-plans 워크플로우에 맞춰 정렬되어 있을 때 가장 일관된 결과를 얻을 수 있습니다.