4.8 KiB
name, description
| name | description |
|---|---|
| writing-plans | 명세가 정해진 다단계 작업을 실행 계획으로 바꿉니다. 코드를 건드리기 전에 구체적인 구현 계획과 작업 순서를 작성해야 할 때 호출합니다. |
구현 계획 작성
이 스킬은 명세나 요구사항이 있는 작업을, 실제 엔지니어가 바로 수행할 수 있는 상세 구현 계획으로 바꾸기 위한 가이드입니다.
개요
계획은 코드베이스 맥락이 거의 없는 개발자도 이해할 수 있도록 충분히 구체적이어야 합니다. 어떤 파일을 수정할지, 어떤 테스트를 작성할지, 무엇을 어떤 순서로 검증할지까지 모두 포함해야 합니다.
핵심 원칙은 다음과 같습니다.
- DRY
- YAGNI
- TDD
- 잦은 커밋
- 작은 단계
계획 문서는 기본적으로 docs/superpowers/plans/YYYY-MM-DD-<feature-name>.md 에 저장합니다.
시작할 때는 현재 구현 계획 작성 단계에 들어왔음을 명확히 선언합니다.
범위 점검
- 명세가 여러 독립 하위 시스템을 포함한다면 계획도 분리합니다.
- 하나의 계획은 자체적으로 구현, 테스트, 검증 가능한 범위를 가져야 합니다.
- 하나의 계획만으로 독립적으로 완료 가능한 단위를 만드는 것이 목표입니다.
파일 구조 먼저 정의
작업을 나누기 전에 어떤 파일을 만들고 수정할지 먼저 정리합니다.
- 각 파일은 하나의 명확한 책임만 가지게 설계합니다.
- 함께 바뀌는 파일은 가까이 두고, 책임 기준으로 나눕니다.
- 기존 코드베이스의 패턴을 따릅니다.
- 지나치게 커진 파일을 다뤄야 한다면 계획 안에 분리 작업을 포함할 수 있습니다.
- 분해 결정은 이 단계에서 고정하는 것이 좋습니다. 계획 후반에 파일 책임이 바뀌면 전체 작업이 흔들립니다.
작업 단위 규칙
각 단계는 2~5분 안에 수행 가능한 하나의 행동이어야 합니다.
- 실패 테스트 작성
- 테스트를 실행해 실패 확인
- 최소 구현 작성
- 테스트를 실행해 통과 확인
- 커밋
이처럼 한 단계에는 한 행동만 담습니다.
좋은 계획은 "무엇을 할지"만 적지 않고, "어떻게 검증할지"까지 함께 적습니다.
계획 문서 헤더
모든 계획 문서는 다음 구조로 시작합니다.
# [기능명] 구현 계획
> **에이전트 작업자용:** 각 작업은 체크박스(`- [ ]`)로 추적합니다.
**목표:** [이 기능이 무엇을 만드는지 한 문장]
**아키텍처:** [접근 방식 2~3문장]
**기술 스택:** [핵심 기술]
---
작업 구조
각 작업은 아래 내용을 포함해야 합니다.
- 대상 파일 경로
- 생성/수정/테스트 파일 구분
- 실제 테스트 코드 예시
- 실행 명령과 기대 결과
- 최소 구현 코드 예시
- 커밋 명령 예시
가능하다면 각 작업은 독립적으로 읽혀야 합니다. 작업을 순서대로 읽지 않아도 필요한 정보가 빠지지 않아야 합니다.
금지 사항
다음과 같은 placeholder는 허용하지 않습니다.
- TBD
- TODO
- 나중에 구현
- 적절한 에러 처리 추가
- 위 내용을 테스트 작성
- Task N과 유사
- 방법 설명만 있고 실제 코드나 명령이 없는 단계
모든 단계는 실행에 필요한 실제 내용을 포함해야 합니다.
다음 표현도 피합니다.
- 적당히 구현
- 필요하면 보완
- 상황에 맞게 처리
- 일반적인 에러 처리 추가
- 위 단계 참고
이런 표현은 실행 정보를 숨기기 때문에 계획 품질을 떨어뜨립니다.
자체 검토
계획 작성 후 아래를 스스로 점검합니다.
- 명세의 모든 요구사항이 작업에 반영됐는가
- placeholder나 빈칸이 남지 않았는가
- 함수명, 타입, 시그니처, 속성명이 작업 간 일관적인가
빠진 요구사항이 있으면 즉시 작업을 추가합니다.
추가로 아래도 확인합니다.
- 각 작업이 실제로 끝나는 단위인지
- 테스트나 검증 단계가 빠지지 않았는지
- 파일 경로가 모호하지 않은지
- 한 작업에 여러 행동이 뭉쳐 있지 않은지
완료 후 인계
계획 저장 후에는 실행 방식을 사용자에게 선택하게 합니다.
- 서브에이전트 기반 실행
- 현재 세션에서 인라인 실행
핵심은, 구현 전에 계획이 먼저 완성되고 검토 가능해야 한다는 점입니다.
기대 결과
이 스킬의 결과물은 다음을 만족해야 합니다.
- 구현자가 문맥 없이도 작업을 시작할 수 있어야 합니다.
- 각 작업은 체크리스트처럼 따라갈 수 있어야 합니다.
- 테스트와 검증 명령이 포함되어 있어야 합니다.
- 문서 안에 실행 가능한 수준의 구체성이 있어야 합니다.