writing-plans

writing-plans 스킬 개요

writing-plans 스킬이 하는 일

writing-plans 스킬은 기능 명세서나 요구사항 문서를, 코딩에 들어가기 전에 상세한 구현 계획으로 바꿔주는 도구입니다. 핵심 역할은 아이디어를 발산하는 것이 아니라, 구현자가 코드베이스 맥락을 거의 모르는 상태에서도 따라갈 수 있도록 파일 단위 가이드, 테스트 단계, 작업 순서를 분명히 담은, 실제로 만들 수 있고 리뷰 가능한 계획을 만드는 데 있습니다.

누가 writing-plans를 써야 하나

이 스킬은 이미 범위가 정리된 요구사항이 있고, 이제 Requirements Planning을 위한 실행 계획이 필요한 엔지니어, 테크 리드, 에이전트 기반 워크플로에 가장 잘 맞습니다. 특히 작업이 여러 파일에 걸치고, 테스트와 문서까지 함께 손봐야 하거나, 원래 명세 작성자가 아닌 다른 사람에게 구현을 넘길 예정일 때 유용합니다.

사용자가 실제로 해결하려는 일

writing-plans 사용자는 보통 구현 과정의 추측을 줄이고 싶어 합니다. 단순히 “계획을 만들어준다”가 아니라, “숨은 전제를 두지 않고도 유능한 엔지니어가 그대로 따라갈 수 있는 계획을 만든다”는 점이 가치입니다. 여기에는 어떤 파일을 건드릴지, 일을 어떻게 잘게 나눌지, 무엇을 테스트할지, 구현 전에 어디서 범위를 분리해야 할지가 포함됩니다.

일반적인 프롬프트와 다른 점

writing-plans skill은 중요한 부분에서 분명한 기준을 갖고 있습니다.

• 작업 분해 전에 먼저 범위를 점검하게 만듭니다
• 태스크를 쓰기 전에 파일별 책임을 먼저 매핑하도록 요구합니다
• 큰 단계 구분보다 작고 테스트 가능한 단위의 진행을 선호합니다
• 구현자가 도메인 맥락을 충분히 모른다는 전제를 둡니다
• 계획이 실제로 구현 가능한지 점검하는 reviewer prompt까지 포함합니다

그래서 단순히 “구현 계획 좀 써줘” 같은 한 줄 프롬프트보다, 특히 핸드오프 품질이 중요할 때 훨씬 강합니다.

writing-plans가 잘 맞는 경우

다음과 같은 상황이라면 writing-plans를 쓰는 것이 좋습니다.

• 문서화된 spec, ticket, 또는 requirements doc이 있다
• 구현 디테일이 중요한 다단계 변경이다
• 코드, 테스트, 문서를 함께 조율해야 한다
• 저장소에서 파일 경계와 작업 순서가 중요하다

반대로 빠른 개요나 대략적인 견적만 필요하다면, 이 스킬은 필요 이상으로 무거울 수 있습니다.

writing-plans 스킬 사용 방법

writing-plans install 맥락

이 스킬 자체 안에는 별도의 패키지 단위 installer가 노출되어 있지 않으므로, 실질적인 writing-plans install 경로는 상위 skill collection을 추가한 뒤 그 안에서 이 스킬을 호출하는 방식입니다.

npx skills add https://github.com/obra/superpowers --skill writing-plans

환경에서 다른 skill loader를 쓴다면, obra/superpowers collection을 설치한 뒤 skills/writing-plans에서 writing-plans를 선택하면 됩니다.

먼저 읽어볼 파일

빠르게 판단하려면 다음 파일부터 보세요.

• skills/writing-plans/SKILL.md
• skills/writing-plans/plan-document-reviewer-prompt.md

SKILL.md에는 실제 계획 수립 워크플로가 들어 있습니다. reviewer prompt는 이 스킬이 기대하는 계획 문서의 품질 기준을 보여주기 때문에, 운영 환경에 쓰기 전에 적합성을 판단하는 데 도움이 됩니다.

이 스킬이 필요로 하는 입력

writing-plans usage는 아래 정보를 줄 때 가장 잘 작동합니다.

• 원본 spec 또는 요구사항 문서
• 대상 repository 또는 관련 codebase 영역
• 아키텍처, 툴링, 마감일, 하위 호환성 등에 대한 제약
• 기본 경로가 아니라면 원하는 계획 문서 출력 위치
• 작업을 여러 개의 독립 계획으로 나눠야 하는지 여부

실제 spec 없이 쓰면 그럴듯한 구조는 만들 수 있어도, 구현 가이드는 약해지는 편입니다.

먼저 요구되는 안내 문구로 시작하기

upstream 지침은 에이전트가 아래 문구를 명시적으로 선언하라고 요구합니다.

I'm using the writing-plans skill to create the implementation plan.

이 스킬을 에이전트 워크플로에 통합한다면, 이 문장은 그대로 유지하는 것이 좋습니다. 어떤 planning standard가 적용되고 있는지 분명해지고, 호출 여부에 대한 혼선을 줄일 수 있습니다.

코딩 전에, 가능하면 전용 worktree에서 사용하기

이 스킬은 구현 전 planning 용도로 설계되었고, upstream의 brainstorming workflow가 만든 전용 worktree에서 실행되는 것을 전제로 합니다. 꼭 그 조합을 그대로 쓸 필요는 없지만 의도는 중요합니다. 코드를 바로 수정하면서 부산물처럼 계획을 만드는 대신, 분리된 맥락에서 먼저 계획을 세워야 계획 문서가 의도적인 산출물이 됩니다.

막연한 목표를 좋은 프롬프트로 바꾸는 방법

약한 프롬프트:

• “Make a plan for adding billing.”

더 강한 프롬프트:

• “Use the writing-plans skill to create an implementation plan for adding team billing to our SaaS app. Spec: docs/specs/team-billing.md. Repo areas likely involved: apps/web, services/billing, db/schema. Constraints: Stripe is already used for individual billing, do not break existing subscriptions, include migration and rollback considerations, and call out tests and docs. If the spec spans independent subsystems, propose separate plans.”

이 프롬프트가 잘 작동하는 이유:

• spec를 명시합니다
• 관련 가능성이 높은 파일이나 모듈을 짚어줍니다
• 작업 분해에 영향을 주는 제약을 알려줍니다
• 지나치게 큰 하나의 계획으로 밀어붙이지 않고, 범위 분리를 허용합니다

스킬의 계획 수립 순서를 따르기

좋은 writing-plans guide라면 저장소가 암묵적으로 전제하는 순서를 따라야 합니다.

1. spec를 여러 개의 계획으로 나눠야 하는지 확인한다
2. 태스크를 쪼개기 전에 파일별 책임을 매핑한다
3. 잘게 나뉜 구현 태스크를 작성한다
4. 테스트, 문서, 검증 단계를 포함한다
5. 완성된 계획을 spec와 대조해 리뷰한다

파일 구조 매핑 단계를 건너뛰면 태스크가 모호해지는 경우가 가장 많습니다.

좋은 출력물에 들어가야 할 것

writing-plans for Requirements Planning으로 만든 좋은 계획에는 보통 다음이 포함되어야 합니다.

• 계획의 목표와 연결된 spec
• 생성하거나 수정할 파일 목록
• 각 파일이 왜 필요한지, 왜 변경되는지
• 독립적으로 완료하고 검증할 수 있을 만큼 작은 태스크
• 단순 코딩 절차가 아닌 테스트 가이드
• 필요하다면 문서 또는 migration 업데이트
• 다른 엔지니어가 막히지 않을 정도의 구체성

출력이 “backend”, “frontend”, “QA” 같은 주제별 단계 구분에 머문다면, 대체로 너무 거친 계획입니다.

기본 계획 저장 위치와 바꿔야 하는 경우

이 스킬은 계획 문서를 다음 경로에 저장하는 것을 권장합니다.

docs/superpowers/plans/YYYY-MM-DD-<feature-name>.md

하지만 저장소에 이미 docs/plans/ 또는 specs/implementation/ 같은 planning 관례가 있다면 그에 맞게 바꾸는 것이 좋습니다. 중요한 것은 일관성과, 나중에 reviewer가 찾을 수 있는 경로입니다.

reviewer prompt 활용법

계획 초안을 만든 뒤에는 plan-document-reviewer-prompt.md를 2차 검토 템플릿으로 사용하세요. 이 템플릿의 리뷰 기준은 실무적입니다.

• 완성도
• spec 정합성
• 태스크 분해 품질
• 실제 구현 가능성

이 점이 writing-plans skill의 분명한 차별점입니다. 단순 생성에서 끝나지 않고, 계획 문서가 합격선에 드는지 확인할 수 있는 가벼운 acceptance check까지 제공합니다.

실제로 잘 먹히는 실무 워크플로

안정적으로 쓸 수 있는 흐름은 보통 이렇습니다.

1. spec와 repo 맥락을 수집한다
2. writing-plans를 실행한다
3. 계획 분리가 적절한지 확인한다
4. 파일 경계와 태스크 크기를 점검한다
5. plan reviewer prompt를 돌린다
6. 구현을 시작하기 전에 계획을 수정한다

이렇게 해야 이 스킬은 단순한 문서 작성 편의 기능이 아니라, 구현 전 planning gate로서 가장 큰 가치를 냅니다.

writing-plans 스킬 FAQ

writing-plans는 초보자에게도 좋은가?

그렇습니다. 다만 초보자라도 어느 정도 구체적인 spec는 있어야 합니다. 이 스킬은 코드베이스 맥락 부족을 파일 단위 가이드와 테스트 지침의 명시화로 보완해줍니다. 반면 진짜 문제가 아직 모호한 제품 기획 단계라면 도움은 제한적입니다.

AI에게 그냥 구현 계획을 요청하는 것과 무엇이 다른가?

일반적인 프롬프트는 겉보기엔 그럴듯하지만 얕은 계획을 내놓는 경우가 많습니다. writing-plans는 파일 단위 분해, 테스트 가능성, 구현자 핸드오프 품질을 강하게 요구하기 때문에 더 실용적입니다. 보통 코딩이 시작된 뒤의 재작업도 그만큼 줄어듭니다.

언제 writing-plans를 쓰지 말아야 하나?

다음 경우에는 굳이 쓰지 않는 편이 낫습니다.

• 변경이 아주 작고 국소적일 때
• 아직 제품 범위를 결정하는 중일 때
• 실행 계획보다 아키텍처 탐색이 더 필요할 때
• 의도적으로 실험적인 작업이라 곧바로 바뀔 가능성이 클 때

이런 상황에서는 형식적인 계획서보다 가벼운 메모가 더 적합할 수 있습니다.

특정 스택이나 프레임워크가 필요한가?

아니요. 이 스킬은 프레임워크 특화형이 아니라 프로세스 중심입니다. 초점이 작업 분해, 파일 책임, 테스트, 리뷰 가능성에 있기 때문에 다양한 스택으로 옮겨 써도 잘 맞습니다.

writing-plans가 큰 spec도 처리할 수 있나?

가능합니다. 다만 범위 점검 단계를 반드시 지켜야 합니다. 원문에서도 서로 독립적인 여러 subsystem은 보통 별도 계획으로 나눠야 한다고 분명히 경고합니다. 억지로 하나의 거대한 계획에 몰아넣으면 태스크 품질이 대체로 떨어집니다.

Requirements Planning에 writing-plans만으로 충분한가?

구현 중심의 Requirements Planning이라면 대체로 충분합니다. 하지만 discovery 단계의 requirements 작업에는 부족합니다. 이 스킬은 “무엇을 만들지”는 이미 정해졌고, 이제 “어떻게 안정적으로 만들지”를 계획해야 하는 상황을 전제로 합니다.

writing-plans 스킬 개선 방법

더 강한 repository 맥락을 제공하기

writing-plans 결과를 가장 쉽게 개선하는 방법은 관련 가능성이 높은 디렉터리, 모듈, 파일을 구체적으로 적어주는 것입니다. 이 스킬은 초반에 파일 책임을 매핑하려고 하기 때문에, 예상 touchpoint를 주면 결과가 훨씬 구체적이고 덜 일반론적으로 바뀝니다.

독립적인 subsystem은 처음부터 분리하기

spec 안에 서로 관련 없는 관심사가 섞여 있다면, 최종 계획을 요청하기 전에 먼저 나누세요. 예:

• auth changes
• billing changes
• admin UI changes

제품 관점에서는 함께 출시되더라도, 구현과 테스트를 독립적으로 할 수 있다면 별도 계획으로 다루는 편이 낫습니다.

파일 책임 매핑을 명시적으로 요청하기

첫 초안이 모호하다면 이렇게 요청하세요.

• “List each file to add or modify and state its responsibility before writing tasks.”

이 요청은 스킬의 구조와 정확히 맞물리며, 흐릿한 작업 분해를 바로잡는 데 대체로 효과적입니다.

태스크를 더 작은 단위로 강제하기

자주 생기는 실패 패턴은 태스크가 너무 커서 안전하게 구현하기 어렵다는 점입니다. 다음을 요청하세요.

• 테스트 가능한 진전을 만드는 태스크
• 태스크별 명확한 경계
• 각 주요 변경 뒤의 명시적인 검증 단계

writing-plans usage는 이 지점에서 가장 크게 좋아집니다. 태스크가 작을수록 리뷰, 할당, 실행이 모두 쉬워집니다.

테스트 요구사항을 구체화하기

단순히 “테스트를 포함해달라”고만 하지 마세요. 대신 다음을 명시하세요.

• 어떤 수준의 테스트가 중요한지
• 어떤 기존 테스트 스위트를 업데이트해야 하는지
• migration, integration, regression 확인이 필요한지 여부

이 스킬은 원래도 테스트를 중요하게 보지만, 제약을 더 구체적으로 줄수록 계획의 실용성이 훨씬 높아집니다.

reviewer 중심 반복으로 초안을 개선하기

reviewer 템플릿을 최종 관문으로만 쓰지 말고 편집 도구로 활용하세요. 첫 번째 계획이 나온 뒤에는 다음을 물어보세요.

• spec에서 빠진 요구사항은 무엇인지
• 어떤 태스크가 실행 가능하지 않은지
• 구현자가 어디에서 막힐 수 있는지
• 범위가 불필요하게 커지고 있는지

이 방식이 “계획을 더 개선해줘” 같은 넓은 요청보다 훨씬 날카로운 2차 초안을 만듭니다.

이런 흔한 실패 패턴을 주의하기

다음과 같은 경우 writing-plans skill의 결과는 약해집니다.

• spec가 불완전할 때
• 파일 경계가 repo에 근거하지 않고 추측에 의존할 때
• 태스크가 구현 단계 없이 결과만 말할 때
• 테스트가 언급만 되고 실제 코드 변경과 연결되지 않을 때
• 하나의 과도하게 큰 계획이 여러 독립 deliverable을 가릴 때

이런 징후가 보이면 스킬을 탓하기 전에 먼저 입력을 보완하는 것이 맞습니다.

구현 선택을 바꾸는 제약을 추가하기

유용한 제약 예시는 다음과 같습니다.

• 하위 호환성 요구사항
• 성능 기대치
• migration 안전성
• 배포 순서
• 문서화 의무
• no-new-dependency 규칙

이런 정보가 있어야 writing-plans for Requirements Planning이 이상적인 일반론이 아니라, 실제 환경에 맞는 계획을 만들어낼 수 있습니다.

실제 핸드오프 기준으로 계획을 검증하기

가장 적절한 품질 테스트는 단순합니다. 맥락이 적은 다른 엔지니어가 이 문서만 보고 반복적인 추가 설명 없이 구현할 수 있는가? 그렇지 않다면, 파일 선택, 태스크 경계, 검증 단계가 충분히 명시될 때까지 계획을 더 다듬어야 합니다.

계획은 DRY하게, 구현 중심으로 유지하기

원문 가이드는 DRY, YAGNI, TDD, 잦은 commit을 강조합니다. 실무적으로는 중복 태스크를 줄이고, 추측성 작업을 피하고, 빠르게 코딩하고 검증할 수 있는 작은 증분을 선호하라는 뜻입니다. 출력 품질을 높이는 데는 문장을 더 늘리는 것보다 이런 원칙을 지키는 편이 훨씬 중요합니다.