Scope-first development plan tooling for Codex and Claude Code.
목적, 범위, 제외 범위, Phase, QA 관점, 테스트 게이트를 먼저 고정해서 구현이 목표 밖으로 확장되지 않게 만드는 개발 계획 스킬/프롬프트 모음입니다.
LLM 기반 구현은 편리하지만, 다음 문제가 자주 발생합니다.
- 구현 중 범위가 조용히 확장됨
- 원래 목표보다 “추가로 더 좋아 보이는 것”까지 건드림
- 테스트 전에 다음 작업으로 넘어감
- 리팩토링 / 추가 개발 히스토리가 문서로 남지 않음
dev-plan-skill은 이 문제를 줄이기 위해 만들어졌습니다.
핵심 아이디어는 단순합니다.
- 작업 시작 전에 개발 목적을 고정한다.
- 이번 작업의 개발 범위와 제외 범위를 먼저 적는다.
- 불명확한 요구사항은 가능한 케이스로 나누고 확인한다.
- 작업을 Phase 단위로 나눈다.
- 기능을 유지보수 가능한 최소 책임 단위로 나누고 역할과 경계를 적는다.
- 각 Phase에 체크박스, 자체 테스트, 이슈 기록을 둔다.
- 별도 QA 관점으로 실패 케이스, 경계값, 회귀 리스크를 점검한다.
- 새로운 작업이 시작될 때마다
implement_YYYYMMDD_HHMMSS.md문서를 새로 만들어 히스토리를 쌓는다.
이 저장소는 두 환경을 함께 지원합니다.
| 항목 | 용도 |
|---|---|
dev-plan-generator/ |
Codex용 skill 폴더 |
.claude/commands/dev-plan.md |
Claude Code용 slash command |
.claude/agents/dev-plan-generator.md |
Claude Code용 custom subagent |
dev-plan-generator/scripts/new_dev_plan.py |
새 개발 계획 문서 골격 생성 스크립트 |
이 도구가 만드는 문서는 거대한 PRD/TRD가 아닙니다.
대신 아래 목적에 집중합니다.
- 이번 작업의 목표 고정
- 이번 작업의 범위 제한
- Phase 기반 구현 순서 정리
- 테스트 완료 후 다음 단계 진행 강제
- 작업별 히스토리 누적
기본 흐름은 다음과 같습니다.
- 범위 고정에 필요한
.md문서만 읽음:README.md,AGENTS.md,CLAUDE.md, 관련docs/*.md, 최근dev-plan/*.md우선 - 목적 / 범위 / 제외 범위 / 참조 문서 / 불명확한 선택지를 정리함
dev-plan/implement_YYYYMMDD_HHMMSS.md생성- 목표와 범위가 같은 workstream일 때만 같은 문서를 업데이트함
- 목표, 범위, 리팩토링 방향이 바뀌면 새 문서를 다시 생성함
생성되는 문서는 기본적으로 아래 구조를 따릅니다.
# implement_YYYYMMDD_HHMMSS.md
작성 일시: `YYYY-MM-DD HH:MM:SS TZ`
이 문서는 이번 개발의 범위를 고정하고, 구현이 목적 밖으로 확장되지 않도록 하기 위한 작업 문서다.
## 개발 목적
...
## 개발 범위
...
## 제외 범위
...
## 참조 문서
...
## 공통 진행 규칙
- 각 Phase는 앞선 Phase의 자체 테스트 완료 후에만 시작한다.
- 구현 중 발생한 이슈는 해당 Phase에서 수정하고 기록한다.
- 체크박스 상태를 실제 진행 상태와 맞게 업데이트한다.
- 문서에 없는 범위 확장은 하지 않는다.
- 요구사항이 불명확하면 가능한 케이스를 나누고 확인 후 진행한다.
- 한 기능은 유지보수 가능한 최소 책임 단위로 나누고, 각 단위의 역할과 경계를 계획에 적는다.
- 계획 밖 옵션/확장/부가 기능을 만들기 위한 분리는 하지 않는다.
- 공통화는 계획 범위 안의 중복을 줄일 때만 수행하고 과도한 추상화는 피한다.
- 기존 프로젝트 API, 공식 SDK, 표준 라이브러리를 우선 검토하고 새 의존성은 범위상 필요할 때만 포함한다.
## Phase 상태 요약
- [ ] Phase 1 완료
- [ ] Phase 2 완료
## QA 관점
- [ ] 실패 케이스와 경계값을 검토한다.
- [ ] 회귀 리스크와 검증 기준을 확인한다.
## Phase 1. <이름>
### 목표
...
### 구현 태스크
- [ ] ...
### 자체 테스트
- [ ] ...
### 이슈 및 수정
- [ ] 발견 이슈 없음
### 완료 조건
- [ ] 구현 완료
- [ ] 자체 테스트 완료
- [ ] 다음 Phase 진행 가능필요한 경우 아래 섹션도 추가할 수 있습니다.
문서 기반 제약 사항확인 필요 사항 / 결정 기록예상 변경 파일 / 영향 범위최종 결과 요약잔여 리스크 / 후속 과제이전 개발 계획
dev-plan-skill/
├── README.md
├── dev-plan-generator/
│ ├── SKILL.md
│ ├── agents/
│ │ └── openai.yaml
│ └── scripts/
│ └── new_dev_plan.py
└── .claude/
├── commands/
│ └── dev-plan.md
└── agents/
└── dev-plan-generator.md
Codex skill 디렉터리에 dev-plan-generator/ 폴더를 넣습니다.
예시:
mkdir -p ~/.codex/skills
cp -R dev-plan-generator ~/.codex/skills/dev-plan-generator설치 후 Codex를 재시작하면 인식이 더 안정적입니다.
아래 요청에서 잘 맞습니다.
- “개발 계획 문서 만들어줘”
- “이번 작업 범위 고정하는 implement 문서 작성해줘”
- “체크박스 기반 phased dev plan 만들어줘”
- “리팩토링용 dev-plan 문서 하나 생성해줘”
- 범위 고정에 필요한 프로젝트
.md문서만 읽음 - 목적 / 범위 / 제외 범위를 상단에 고정
- 불명확한 요구사항은 가능한 케이스/옵션으로 나누고 확인
- 순차적인 Phase로 구현 태스크 생성
- 각 Phase마다 자체 테스트 추가
- 별도
QA 관점으로 실패 케이스, 경계값, 회귀 리스크 검토 - 같은 목표와 범위의 작업은 같은 문서를 업데이트
- 목표, 범위, 리팩토링 방향이 바뀌면 새
implement_*.md파일 생성
Claude Code에서는 두 방식으로 사용할 수 있습니다.
이 저장소에는 프로젝트용 slash command가 포함되어 있습니다.
경로:
.claude/commands/dev-plan.md
사용 예시:
/dev-plan 로그인 API 1차 구현 범위 문서 작성
이 command는 dev-plan-generator/SKILL.md와 scripts/new_dev_plan.py를 참조해 같은 워크플로우를 따르도록 구성되어 있습니다.
경로:
.claude/agents/dev-plan-generator.md
이 subagent는 아래 상황에서 쓰기 좋습니다.
- 구현 전 계획 문서를 먼저 정리하고 싶을 때
- 여러 작업 중 scope 고정 역할을 분리하고 싶을 때
- 개발 계획 문서를 반복적으로 생성/업데이트할 때
원하는 프로젝트 루트에 아래를 복사하면 됩니다.
.claude/commands/dev-plan.md.claude/agents/dev-plan-generator.mddev-plan-generator/
new_dev_plan.py는 문서를 똑똑하게 작성하는 도구가 아니라, 문서 골격을 빠르게 생성하는 도구입니다.
즉:
- 문서 해석 / 범위 정의 / 제약 추출 → 에이전트가 담당
- 파일 생성 / 기본 섹션 생성 → 스크립트가 담당
python3 dev-plan-generator/scripts/new_dev_plan.py \
--root /path/to/project \
--purpose "로그 경로 정리와 회귀 테스트 추가" \
--scope "기존 로그 집계 리팩토링과 테스트 보강에 한정" \
--reference "README.md" \
--reference "docs/logging.md" \
--exclude "신규 기능 추가" \
--exclude "무관한 구조 변경" \
--phase "로그 수집 경로 정리" \
--phase "회귀 테스트 보강" \
--phase "문서 동기화"| 옵션 | 설명 |
|---|---|
--root |
dev-plan/ 폴더를 생성할 프로젝트 루트 |
--purpose |
이번 개발의 목적 |
--scope |
이번 개발 범위 |
--exclude |
제외 범위 항목, 반복 가능 |
--reference |
참조 문서 경로/링크, 반복 가능 |
--phase |
Phase 이름, 반복 가능 |
--previous-plan |
이전 개발 계획 문서 경로 |
기본 출력 위치:
dev-plan/implement_YYYYMMDD_HHMMSS.md
이 도구는 아래 패턴으로 쓸 때 가장 효과적입니다.
- 새
implement_*.md생성 - 목적 / 범위 / 제외 범위 먼저 고정
- 같은 문서 업데이트
- 체크박스 상태와 이슈 기록 갱신
- 목표와 범위가 같은 workstream인지 확인
- 새
implement_*.md생성 - 이전 문서를
참조 문서에 연결 - 목표, 범위, 리팩토링 방향 변경을 새 workstream으로 기록
이렇게 하면 개발 계획 문서가 자연스럽게 작업 히스토리가 됩니다.
이 저장소는 아래 원칙을 따릅니다.
- Scope-first: 구현보다 범위 고정이 먼저
- Lightweight: 거대한 설계 문서가 아니라 작업 문서
- Phased: 큰 작업을 순차 Phase로 분해
- Minimal modularity: 기능을 유지보수 가능한 최소 책임 단위로 나누되 계획 밖 확장을 만들지 않음
- Test-gated: 테스트 완료 전 다음 Phase 금지
- History-friendly: 작업 단위별 문서 누적
- QA-aware: 실패 케이스, 경계값, 회귀 리스크를 별도 관점으로 확인
- Handoff-ready: 다른 에이전트나 개발자가 이어받을 수 있게 목적, 범위, 순서, 검증 기준을 남김
- Tool-agnostic workflow: Codex와 Claude Code 모두 같은 사고방식 사용
dev-plan-generator/는 Codex skill 구조를 따릅니다.SKILL.md+agents/openai.yaml+scripts/구성을 포함합니다.
.claude/commands/기반 custom slash command 포함.claude/agents/기반 custom subagent 포함- 둘 다 같은 workflow를 공유하도록 작성됨
현재 저장소의 Codex skill은 skills-ref validate 기준으로 검증할 수 있습니다.
예시:
skills-ref validate ./dev-plan-generator검증 포인트:
- skill 이름과 폴더명 일치
SKILL.mdfrontmatter 정합성- 스크립트 포함 구조 유지
- Claude Code용 command / agent 파일 존재
- 문서 구조와 참조 경로 일관성
- 기능 구현 전에 범위 고정 문서 만들기
- 리팩토링 시작 전에 목표와 금지선 고정하기
- 장기 작업을 Phase별로 나눠 체크박스로 추적하기
- 불명확한 요구사항을 케이스별로 나누고 결정 기록 남기기
- QA 관점에서 실패 케이스와 회귀 리스크를 미리 드러내기
- 테스트 완료 전 다음 단계로 넘어가지 않도록 문서 게이트 만들기
- 추가 개발이 생길 때마다 새 문서를 생성해 히스토리 남기기
- Anthropic Claude Code tutorials: https://docs.anthropic.com/en/docs/claude-code/tutorials
- Anthropic Claude Code slash commands: https://docs.anthropic.com/en/docs/claude-code/slash-commands
- Anthropic Claude Code subagents: https://docs.anthropic.com/en/docs/claude-code/sub-agents
dev-plan-skill은
- Codex에서는 skill로
- Claude Code에서는 command / subagent로
같은 개발 계획 워크플로우를 재사용할 수 있게 해줍니다.
핵심 목적은 하나입니다.
구현을 더 많이 하게 만드는 것이 아니라, 이번 작업이 어디까지인지 먼저 고정하고 일관되게 끝까지 가게 만드는 것.