Skip to main content
command CX Codex

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

Install into Claude Code · Manually: put the files in place All methods and platforms ↓
.claude/commands/dev-docs.md
Open on GitHub

What 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.md

Call it with /dev-docs. For all projects use ~/.claude/commands/

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

Similar slash commands

All slash commands for Code review and refactoring →

From the same set16

The whole set →
route-research-for-testing route-research-for-testing is a Claude Code command that collects changed routes from the current session and tests them via cURL to check edited API endpoints. CX Codex +1 ★ 10,055repo stars verify-setup verify-setup — a command that diagnoses your project's infrastructure, identifies what's broken, and guides you through fixes. Use it when Claude Code hooks, dependencies or configs fail. CX Codex +1 ★ 10,055repo stars source-command-verify-setup source-command-verify-setup executes infrastructure health checks and repairs broken configurations or hook dependencies. CX Codex +1 ★ 10,055repo stars dev-docs-update The dev-docs-update command records active work before a context reset, covering task files, project memory, unfinished work, and handoff notes. CX Codex +1 ★ 10,055repo stars auto-error-resolver auto-error-resolver is a subagent that fixes TypeScript compilation errors from hook reports and verifies the build with tsc. CX Codex ★ 10,055repo stars frontend-error-fixer The frontend-error-fixer subagent investigates frontend failures during builds and in the browser. Use it for TypeScript, React, network, and rendering problems. CX Codex ★ 10,055repo stars refactor-planner refactor-planner — a subagent that studies your code structure and writes a phased refactoring plan with risk assessment. Use it before reworking a legacy module or an oversized component. CX Codex ★ 10,055repo stars plan-reviewer plan-reviewer reviews technical plans, migrations, and system integrations before writing code. Catches architectural traps, missing dependencies, and edge cases early. CX Codex ★ 10,055repo stars

Project sponsors

Companies that keep this analytics open