Claude Code로 구현 계획을 만드는 writing-plans 스킬
機械翻訳 / Machine-translated
機械翻訳 / Machine-translated
원문: Claude Code로 구현 계획을 만드는 writing-plans 스킬（cccskills）
스킬 페이지: writing-plans
이 글의 결론
writing-plans를 도입하면, 사양이나 요건을 전달하는 것만으로 구현 계획을 만들 수 있습니다.
변경할 파일, 함수의 타입, 테스트, 확인 커맨드까지 담긴 계획이 코드보다 먼저 완성되는 구조입니다.
이 글에서는 계획서의 내용과 자체 점검 항목, Claude Code 및 Codex에 도입하는 방법을 설명합니다.
후반부에서는 계획을 다른 에이전트에게 넘겨 구현하게 하는 방법도 다룹니다.
사양을 전달하면, 코드에 손을 대기 전에 계획서 한 장이 완성됩니다.
태스크별 변경 파일과 테스트 절차까지 담긴 것입니다.
예를 들어 다음과 같이 요청합니다.
첨부한 사양으로 구현 계획을 만들어주세요.
아직 코드는 작성하지 마세요.
에이전트는 먼저 writing-plans를 사용하겠다고 선언하고, 계획을 docs/superpowers/plans/YYYY-MM-DD-<feature-name>.md에 저장합니다.
맨 앞에 나오는 것은 목적, 구성 방침, 사용 기술, 원본 사양의 위치입니다.
그 아래에는 사양 전체에 관한 제약과 「Review Focus」 항목이 이어집니다.
Review Focus에 올라오는 것은, 어떤 태스크의 테스트도 다루지 않은 입력이나 실패 조건입니다.
각 태스크는 다음 세 가지 요소로 작성됩니다.
| 요소 | 작성 내용 |
|---|---|
| Files | 생성·변경·테스트할 파일의 경로. 변경하는 파일은 줄 번호까지 |
| Interfaces | 이전 태스크에서 받는 것과, 다음 태스크에 넘길 함수명·인수·반환값 타입 |
| 절차 | 체크박스가 달린 절차. 실패할 테스트 작성, 실패 확인, 최소한의 구현, 성공 확인, 커밋 |
계획을 다 작성하면, 에이전트는 계획을 검토해 달라고 요청하고, 구현 진행 방식을 물어본 뒤 멈춥니다.
확인 없이 구현이 시작되는 일은 없습니다.
writing-plans는 사양을 「구현자가 스스로 결정할 수 없는 것」의 목록으로 변환하는 스킬입니다.
다음 네 가지 기능으로, 재작업의 원인이 되는 모호함을 구현 전에 줄입니다.
계획의 독자로 상정하는 것은, 이 코드베이스도 사양도 본 적 없는 구현자입니다.
그래서 계획에는 건드릴 파일, 함수의 이름과 타입, 사양에 있는 구체적인 값, 각 태스크를 뒷받침하는 테스트를 명시합니다.
함수의 내부 구현은 작성하지 않습니다.
다만 타입과 테스트만으로는 결정되지 않는 알고리즘은 예외입니다.
하나의 태스크는, 자체 테스트 사이클을 갖고 리뷰에서 단독으로 되돌릴 수 있는 최소 단위입니다.
설정이나 사전 준비, 문서 작업은 그것을 필요로 하는 태스크에 포함하는 것이 원칙입니다.
사양이 독립된 여러 서브시스템에 걸쳐 있는 경우, 에이전트는 서브시스템별로 계획을 나누도록 제안합니다.
계획 작성이 끝나면, 에이전트는 사양과 대조하여 다음 5개 항목을 확인합니다.
발견된 문제는 그 자리에서 수정하고, 대응하는 태스크가 없는 요건에는 태스크를 추가합니다.
Task 3에서 clearLayers(), Task 7에서 clearFullLayers()처럼 작성한 이름의 불일치를 잡아내는 것도 이 단계입니다.
각 태스크의 Interfaces 항목에 작성되는 것은, 받는 것과 넘기는 것의 정확한 타입입니다.
구현자는 자신의 태스크만 읽어도, 인접한 태스크와 이름이나 타입을 맞출 수 있습니다.
계획의 첫 부분에는 원본 사양의 위치도 작성됩니다.
받은 쪽은 계획과 사양을 나란히 읽을 수 있습니다.
writing-plans는 obra/superpowers에 포함된 스킬 중 하나로, 포함 파일은 SKILL.md뿐입니다.
커맨드로 설치하려면 다음을 실행하세요.
설치할 에이전트는 Claude Code나 Codex 등에서 선택할 수 있습니다.
npx skills add https://github.com/obra/superpowers --skill writing-plans
에이전트에게 설치해 달라고 할 경우, 다음 문장을 그대로 전송하세요.
내용을 확인한 후 배치하도록 요청하는 내용입니다.
次の Agent Skill をインストールしてください。
https://github.com/obra/superpowers/tree/main/skills/writing-plans
まず SKILL.md と付属ファイルの中身を確認し、不審な処理（外部への送信、認証情報の読み取りなど）がないことを確かめてから、Claude Code なら ~/.claude/skills/writing-plans/、Codex なら ~/.agents/skills/writing-plans/ に配置してください。
배치 위치는 모든 프로젝트에서 사용할지, 특정 프로젝트에서만 사용할지에 따라 선택합니다.
| 에이전트 | 모든 프로젝트에서 사용 | 특정 프로젝트에서만 사용 |
|---|---|---|
| Claude Code | ~/.claude/skills/ | 프로젝트의 .claude/skills/ |
| Codex | ~/.agents/skills/ | 프로젝트의 .agents/skills/ |
요청문에는 사양의 위치와 계획의 저장 위치 및 실행 방법 희망 사항을 함께 전달하면 빠르게 진행됩니다.
대표적인 요청 방법은 다음 세 가지입니다.
이 기능 추가 요건으로, 변경할 파일과 테스트 절차가 포함된 구현 계획을 만들어줘.
저장 위치는 docs/plans/로 해줘.
계획은 지정한 docs/plans/에 저장됩니다.
저장 위치 희망 사항이 기본 위치보다 우선되기 때문입니다.
각 태스크에는 파일 목록과, 테스트부터 작성하기 시작하는 체크박스가 달린 절차가 붙습니다.
계획의 Task 2에서, 어떤 테스트를 어떤 커맨드로 실행하고, 무엇이 출력되면 성공인지 알려줘.
계획의 확인 절차에는 실행 커맨드와 성공을 나타내는 출력이 작성되어 있습니다.
그래서 반환되는 것은, 실패를 확인하는 단계와 성공을 확인하는 단계 각각에 대해, 계획에 작성된 그대로의 커맨드와 기대 결과입니다.
계획이 완성되면, 태스크별로 다른 에이전트에게 구현을 맡기고 싶어.
실행 방법을 미리 전달해 두면, 에이전트는 방법을 다시 묻지 않고 계획 확인만 요청합니다.
전달하지 않은 경우에는 다음 두 가지 중에서 선택하도록 요청하며, 어느 쪽을 권장하는지 이유와 함께 제시합니다.
| 방법 | 진행 방식 | 특징 |
|---|---|---|
| Subagent-driven | 태스크별로 새로운 서브에이전트가 구현하고, 새로운 리뷰어가 확인한 후 다음으로 진행. 마지막에 브랜치 전체를 리뷰 | 가장 꼼꼼함. 태스크와 리뷰마다 새로운 컨텍스트를 사용 |
| Native | 같은 세션에서 전체 태스크를 구현하고, 마지막에 가장 능력이 높은 모델의 리뷰어가 브랜치 전체를 확인 | 가장 저렴하고 빠름. 중간에 독립적인 리뷰는 없음 |
writing-plans는 사양이나 요건이 준비된 상태에서 사용하는 스킬입니다.
전제가 되는 사양은 사람이 준비하고 내용을 확인해 두세요.
사양이 모호한 채로 전달하면, 계획도 그 모호함을 그대로 이어받습니다.
구현 단계에서는 다른 스킬을 호출하는 구조로 되어 있습니다.
Subagent-driven이라면 subagent-driven-development, Native라면 executing-plans가 필요합니다.
둘 다 obra/superpowers에 포함되어 있으니, 함께 설치해 두세요.
계획은 그대로 수락하지 말고, 직접 읽고 판단하세요.
특히 Review Focus 항목에는 테스트로 다루지 못한 입력이나 실패 조건이 나열됩니다.
실제 사용자에게 영향을 미칠 것 같은 순서대로 확인하는 것이 좋습니다.
라이선스는 MIT입니다.
설치 전에 SKILL.md의 내용을 읽고 지시 내용을 확인하세요.
같은 obra/superpowers의 스킬 중에서, 계획의 전후를 연결하는 것 세 가지를 소개합니다.
brainstorming은 계획의 전 단계에서 목적이나 제약을 대화로 정리하고, 작업 규모에 맞는 설계를 정리합니다.
사양이 아직 확정되지 않았을 때는 이것이 출발점입니다.
subagent-driven-development는 계획을 태스크별로 다른 에이전트에게 맡기고, 사양 준수 여부와 코드 품질을 확인하면서 진행합니다.
executing-plans는 같은 세션에서 태스크를 순서대로 실행하고, 마지막에 브랜치 전체를 리뷰합니다.
사양이나 요건이 있는 것이 전제입니다.
아직 확정되지 않은 경우에는 먼저 brainstorming으로 목적이나 제약을 정리하고, 거기서 계획을 만드는 흐름이 됩니다.
기본 저장 위치는 docs/superpowers/plans/ 아래입니다.
날짜와 기능명을 붙인 Markdown 파일로 저장됩니다.
요청 시 저장 위치를 지정하면 그쪽이 우선됩니다.
진행되지 않습니다.
계획을 저장하고 자체 점검한 후, 사용자의 리뷰를 기다리며 멈춥니다.
구현을 담당하는 것은 subagent-driven-development 또는 executing-plans입니다.
계획 작성 형식의 예시는 Python과 pytest이지만, 구현자가 프로젝트의 언어로 작성하는 것을 전제로 합니다.
계획에 작성하는 것은 파일, 타입, 테스트, 확인 커맨드이므로 언어에 맞는 내용이 됩니다.
writing-plans는 AI 에이전트에게 바로 코드를 작성하게 해서 재작업이 많은 분께 적합한 스킬입니다.
사양으로부터, 변경 파일·함수 타입·테스트·확인 커맨드를 작성한 계획을 먼저 만듭니다.
그 위에서 이름 불일치나 사양 누락을 자체 점검합니다.
완성된 계획은 태스크 단위로 다른 에이전트나 담당자에게 넘길 수 있습니다.
먼저 작은 기능 추가 사양으로 시험해 보세요.
cccskills 페이지
이 글은 cccskills의 읽을거리 「Claude Code로 구현 계획을 만드는 writing-plans 스킬」의 전재입니다.
스킬의 상세 내용과 설치 방법은 cccskills의 writing-plans 페이지에 있습니다.