implementation-planning（实施规划）

Implementation Planning

Take a ticket, shaped work, or technical challenge and create a detailed implementation plan that any developer or agent can follow.

Plan Mode

Multi-phase plans → use plan mode:

1. If not already in plan mode, call EnterPlanMode
2. Research using sub-agents (see below)
3. Write plan to BOTH locations:

- The internal plan file (path in system message) - thoughts/plans/YYYY-MM-DD-descriptive-name.md (persistent)

1. Call ExitPlanMode when done

Simple designs (single-phase, quick approach discussion) → skip plan mode, just discuss.

Plan File Storage

Save plans to thoughts/plans/ — this is the persistent, shareable location. The internal Claude Code plan file is temporary.

thoughts/plans/YYYY-MM-DD-descriptive-name.md

Use TODAY'S DATE from system context as prefix (e.g., "Today's date" in env info).

Design Philosophy

Before writing plans, read references/software-design-philosophy.md. Apply these principles when designing module boundaries, interfaces, and decomposition. Key checks: modules should be deep, information hiding, define errors out of existence, design it twice.

Principles

• Research first — understand the codebase before proposing solutions
• Be specific — include file paths, function names, code snippets
• Be skeptical — question assumptions, identify risks early
• Decide, don't ask — every open question gets a recommended resolution with reasoning. Never present a question without proposing what you'd do
• Be practical — focus on incremental, testable changes
• Agent-agnostic — plan should work for any implementer
• Follow patterns — match existing codebase conventions

Process

1. Gather Context

Launch parallel Explore sub-agents before planning. Each serves a different purpose:

# 1. LOCATE — find where relevant files live (don't read contents, just map locations)
Agent(subagent_type="Explore", prompt="Find all files related to [feature/domain].
  Group by: routes, use-cases/business logic, components, DB schema, tests.
  Report file paths and directory structure only, don't read contents.")

# 2. PATTERNS — find similar implementations to model after (read code, extract complete examples)
Agent(subagent_type="Explore", prompt="Find similar implementations to [what we're building].
  Read the code thoroughly. Extract complete working examples with imports.
  Note file organization, naming conventions, error handling approach.")

# 3. ANALYZE — trace how an existing related feature works end-to-end
Agent(subagent_type="Explore", prompt="Analyze how [related feature] is implemented.
  Trace the data flow from entry point to DB/API.
  Map key functions, their inputs/outputs, and error handling paths.")

Use all three when the feature is complex. For simpler tasks, locate + patterns may suffice.

Also gather:

• Related research docs in thoughts/research/
• The tech stack:

**Package manager:** pnpm/npm/yarn
**Build tool:** turbo/nx/none
**Language:** TypeScript (strict mode?)
**Runtime:** Node.js/Bun/Deno
**Framework:** Fastify/Express/Hono
**Database:** Postgres + Drizzle/Prisma
**Testing:** Vitest/Jest
**Patterns to follow:** [reference existing implementations]

For monorepo projects:

• Package structure from pnpm-workspace.yaml
• Build configuration from turbo.json
• Existing packages for patterns to follow

Ask clarifying questions if requirements are ambiguous.

2. Present Options (If Multiple Approaches Exist)

Present trade-offs clearly:

• Option A: [approach] — Pros/Cons
• Option B: [approach] — Pros/Cons
• Recommendation: [which and why]

Get alignment before detailed planning.

3. Write the Plan

Create a structured plan following the output format below.

Output Format

# [Title] - Implementation Plan

## Overview
[1-2 sentences: what we're building and why]

## Acceptance Criteria
[Link to the shape doc: `thoughts/research/YYYY-MM-DD-name.md`]
[The shape doc is the canonical source. Do NOT restate or reinterpret criteria here — qa-test will consume them from the shape doc verbatim.]
[If no shape exists (tiny/unshaped work), list criteria here directly using the same rules as shaping-work: independently testable, observable behavior, no vague language.]

## Current State
[What exists now, what's missing, relevant code locations]

## Desired End State
[What should work when done, how to verify — include example commands/usage]

## Out of Scope
[Explicitly list what we're NOT doing — prevents scope creep]

## Implementation Approach
[High-level strategy and reasoning]

---

## Phase 1: [Descriptive Name]

### What This Accomplishes
[Summary of this phase's goal]

### Changes

**File**: `path/to/file.ext`

// Complete code to add or modify // Not snippets — full implementation

**File**: `path/to/another.ext`

// Complete code

### Phase Checks

- [Specific command to run — build, typecheck, unit test]
- [Expected output or behavior]

*Phase Checks are technical gates (build passes, typecheck clean, unit tests green). They are NOT acceptance criteria. ACs are verified by qa-test at the end against the shape doc.*

---

## Phase 2: [Descriptive Name]

[Same structure as Phase 1]

---

## Testing Strategy

### Manual Verification

Step-by-step commands to verify everything works

command1 command2

### Automated (if applicable)

- Unit tests: [what to test]
- Integration tests: [what scenarios]

## File Summary

directory/ ├── file1.ext # Purpose ├── file2.ext # Purpose └── subdirectory/ └── file3.ext # Purpose

**Total new files:** N files

## Related Research

- `thoughts/research/YYYY-MM-DD-name.md` — [what it covers]

## Open Questions

Every question includes a recommended resolution. Proceeding with these unless you steer otherwise.

- **[Question]** Recommend: [option] — [why] Discarded: [option] ([why not])

Phase Guidelines

Good phases:

• Each phase is independently verifiable via Phase Checks
• Earlier phases don't break existing functionality
• Later phases build on earlier ones
• Can pause between phases if needed

Phase sizing:

• Small enough to verify quickly
• Large enough to be meaningful
• Typically 1-3 files per phase
• Each phase should have clear verification steps

Code in phases:

• Include COMPLETE code, not snippets
• Show the full file content or the full function
• Never use "..." or "// rest of code"
• Someone should be able to copy-paste and have it work

What Makes a Good Plan

Good (specific, actionable):

• File paths exist or clearly describe where to create
• Code snippets show COMPLETE implementation
• Verification steps are concrete commands
• Expected outputs documented

Bad (vague, hand-wavy):

• "Update the relevant components"
• "Add appropriate error handling"
• "Test thoroughly"
• Code snippets with "..." placeholders

Example

Input ticket: "Add database package with Drizzle ORM"

Output plan (abbreviated):

# Database Package - Implementation Plan

## Overview
Create `packages/db` with Drizzle ORM for PostgreSQL, following monorepo patterns from jp-partner-platform.

## Current State
- Monorepo exists with Fastify API + Temporal worker
- Postgres in docker-compose (port 5462)
- No database package yet

## Desired End State

Package builds successfully

pnpm --filter=@repo/db build

Migrations work

pnpm --filter=@repo/db generate pnpm --filter=@repo/db migrate

Types available in other packages

import { users } from "@repo/db/schema"

## Out of Scope

- API endpoints using the database
- Seed data
- Production deployment config

---

## Phase 1: Package Setup

### What This Accomplishes

Create the package skeleton with Drizzle configuration.

### Changes

**File**: `packages/db/package.json`

{ "name": "@repo/db", "type": "module", "exports": { ".": { "default": "./dist/index.js" }, "./schema": { "default": "./dist/schema/index.js" } }, "scripts": { "build": "tsc", "generate": "drizzle-kit generate", "migrate": "drizzle-kit migrate" }, "dependencies": { "drizzle-orm": "^0.44.0", "postgres": "^3.4.7" }, "devDependencies": { "drizzle-kit": "^0.31.0" } }

**File**: `packages/db/drizzle.config.ts`

import { defineConfig } from "drizzle-kit"

export default defineConfig({ schema: "./src/schema/index.ts", out: "./drizzle", dialect: "postgresql", dbCredentials: { url: process.env.DATABASE_URL ?? "postgresql://postgres:postgres@localhost:5462/mydb", }, })

### Phase Checks

- `pnpm install` succeeds
- `pnpm --filter=@repo/db build` succeeds

---

## Phase 2: Schema Definition

[...]

Handoffs

• After plan approval, use /dev-skills:implement-change to execute phase by phase
• The plan in thoughts/plans/ serves as the source of truth during implementation
• For plans that introduce new UI, check docs/design.md §Functional patterns first — extend an existing pattern before designing a new one. If unclear what the product's design language is, run /dev-skills:design-language in Capture mode against the inspiration source to establish it before planning