dev-docs — Claude Code command: strategic project planning
dev-docs generates a detailed implementation plan for any task: analyzes your codebase, breaks work into phases, creates task checklists with dependencies and effort estimates, and persists across context switches.
MIT ★ 10,055 updated 2026-07-13
.claude/commands/dev-docs.mdWhat dev-docs does
dev-docs takes a description of what needs planning—"refactor authentication", "migrate to microservices"—examines relevant code files, and builds a strategic document covering scope analysis, current state, target state, implementation phases, tasks with acceptance criteria and effort levels, risk assessment, success metrics, and resource needs.
The command creates three files in dev/active/[task-name]/: a comprehensive plan (*-plan.md), a reference guide for dependencies and decisions (*-context.md), and a progress checklist (*-tasks.md). Each file includes a last-updated timestamp so plans don't decay invisibly as context resets during development.
Tasks include effort estimates (S/M/L/XL), priority ordering, and dependency mapping. The command checks for PROJECT_KNOWLEDGE.md, BEST_PRACTICES.md, TROUBLESHOOTING.md, and dev/README.md to embed local standards and constraints—without them, recommendations might not align with how your team actually works.
What it helps with
- Break a large initiative into phases with clear task dependencies
- Create task checklists that survive context resets
- Analyze current architecture before a major refactor
- Estimate effort and identify risks in a strategic plan
- Document decisions and reasoning so context doesn't disappear
Example prompts for the agent
- dev-docs refactor authentication system with OAuth2 integration
- dev-docs migrate monolith to microservices: split into separate deployable components
- dev-docs add Redis caching layer for frequently accessed queries
How to install dev-docs
Manually: put the files in place
.claude/commands/dev-docs.mdCall it with /dev-docs. For all projects use ~/.claude/commands/
Manually: put the files in place
~/.codex/prompts/dev-docs.mdCall it with /prompts:dev-docs. Codex marks this format deprecated in favour of skills
Manually: put the files in place
.github/prompts/dev-docs.prompt.mdManually: put the files in place
.gemini/commands/dev-docs.tomlGemini stores commands as TOML: the prompt text goes into the prompt field
Questions about dev-docs
How do I install dev-docs in Claude Code?
Copy .claude/commands/dev-docs.md from the repository to the .claude/commands/ folder in your project. For Codex, use ~/.codex/prompts/dev-docs.md.
What does dev-docs do?
Generates a strategic plan: analyzes your codebase, breaks the task into phases with numbered tasks, effort estimates (S/M/L/XL), and dependency notes, then writes three persistent files (*-plan.md, *-context.md, *-tasks.md) that survive context resets.
Do I need to create PROJECT_KNOWLEDGE.md?
No, it's optional. The command looks for it if present to understand your architecture; without it, the plan builds from codebase analysis and your description alone.
Source text
dev-docs.md · MIT
---
description: Create a comprehensive strategic plan with structured task breakdown
argument-hint: Describe what you need planned (e.g., "refactor authentication system", "implement microservices")
---
You are an elite strategic planning specialist. Create a comprehensive, actionable plan for: $ARGUMENTS
## Instructions
1. **Analyze the request** and determine the scope of planning needed
2. **Examine relevant files** in the codebase to understand current state
3. **Create a structured plan** with:
- Executive Summary
- Current State Analysis
- Proposed Future State
- Implementation Phases (broken into sections)
- Detailed Tasks (actionable items with clear acceptance criteria)
- Risk Assessment and Mitigation Strategies
- Success Metrics
- Required Resources and Dependencies
- Timeline Estimates
4. **Task Breakdown Structure**:
- Each major section represents a phase or component
- Number and prioritize tasks within sections
- Include clear acceptance criteria for each task
- Specify dependencies between tasks
- Estimate effort levels (S/M/L/XL)
5. **Create task management structure**:
- Create directory: `dev/active/[task-name]/` (relative to project root)
- Generate three files:
- `[task-name]-plan.md` - The comprehensive plan
- `[task-name]-context.md` - Key files, decisions, dependencies
- `[task-name]-tasks.md` - Checklist format for tracking progress
- Include "Last Updated: YYYY-MM-DD" in each file
## Quality Standards
- Plans must be self-contained with all necessary context
- Use clear, actionable language
- Include specific technical details where relevant
- Consider both technical and business perspectives
- Account for potential risks and edge cases
## Context References
- Check `PROJECT_KNOWLEDGE.md` for architecture overview (if exists)
- Consult `BEST_PRACTICES.md` for coding standards (if exists)
- Reference `TROUBLESHOOTING.md` for common issues to avoid (if exists)
- Use `dev/README.md` for task management guidelines (if exists)
**Note**: This command is ideal to use AFTER exiting plan mode when you have a clear vision of what needs to be done. It will create the persistent task structure that survives context resets.
© diet103 · MIT · diet103/claude-code-infrastructure-showcase