Bulletproof — Adaptive Development Workflow

Author: Artemiy Miller (@artemiimillier) · Telegram · who.ismillerr@gmail.com · TG Channel Version: 5.0 · March 2026 License: MIT Compatible: Claude Code, Codex, Gemini CLI, Cursor, Windsurf, OpenCode

Core Principle

Code to solve problems, not code for code's sake.

Before EVERY change ask: "Does this actually solve our problem? Is this the most efficient solution?" If the answer isn't clear — stop, research alternatives, pick the best one.

Pick Your Mode

Not every task needs the full pipeline.

How stages relate: Stages 5-6-7 (Self-Audit, Verification, Impact) run inside each implementation phase as an inner loop. Stages 8-12 run once after all phases complete as an outer loop.

Context Management (ALWAYS applies)

The 40% Rule

Code quality degrades when context fills beyond 40% ("Dumb Zone"). Rules:

• Stay within 40-60% of the context window
• Manual /compact at 50% — don't wait for auto
• If overloaded: save progress → /clear → fresh start

Fresh Context Between Stages

Every major stage = clean context window:

1. Save stage artifact (research / spec / plan / handoff)
2. /clear
3. Start new stage pointing the agent to the artifact path

Handoff Protocol

Before /clear always create progress/<task>-handoff.md. See templates/handoff.md for format.

Progressive Disclosure

Don't dump the entire codebase into context:

• Research: sub-agents → compact summary
• Planning: summary + key interfaces only
• Implementation: only files for current phase
• In CLAUDE.md: "For details, see path/to/docs.md" (not @file)

Stage 1: Deep Research

Mode: Read-Only. No code. No changes.

• Launch parallel Explore agents (1 per area: structure, patterns, deps, tests)
• WebSearch: Who has already solved this problem? How did they solve it? What is the most efficient known solution? Don't reinvent — find the best existing approach first.
• Analyze all findings and make a conclusion: which solution is the BEST and why. The research artifact must end with a clear recommendation, not just a list of options.
• Save to thoughts/research/YYYY-MM-DD-<task>.md (see templates/research.md for format)

→ /clear

Stage 2: Spec / PRD

Mode: Read + Write only in specs/. No code.

Spec = WHAT and WHY. Not how. Spec = contract.

• Read Research Artifact from thoughts/research/
• Create specs/YYYY-MM-DD-<name>.md (see templates/spec.md for format)
• Key sections: Problem, Goal, Scope, Acceptance Criteria, Constraints, Non-Goals

Skip for size S tasks. → /clear

Stage 3: Planning + Questions

Mode: Read + Write only in plans/. No code yet.

• Read both Spec (specs/) and Research (thoughts/research/)
• Launch Plan agents to check the approach
• Find gaps: what's unthought? What edge cases? What could break?
• Be creative and proactive: anticipate ALL possible problems BEFORE writing code. Think several steps ahead. What could go wrong in a week? A month? Under load? With unexpected user behavior? Solve problems before they exist.
• WebSearch: How have others solved this exact problem? What libraries/patterns exist? What's the proven best practice? Choose the most efficient solution, not the first one that comes to mind.
• After Plan agents verify the approach — rewrite the plan into an improved version incorporating all findings, edge cases, and research results. Not just patch it — rewrite it better.

Challenge Loop (mandatory before finalizing plan)

Before finalizing the plan, answer 3 questions:

1. DOES THIS SOLVE THE PROBLEM?
   Compare every plan item against acceptance criteria from spec.
   If any criterion is uncovered — the plan is incomplete.

2. IS THIS THE MOST EFFICIENT SOLUTION?
   Search: who has already solved this problem? What approach did they use?
   Name 2-3 alternative approaches (including ones found via research).
   For each: pros, cons, effort.
   Justify why the chosen approach is better than all alternatives.

3. IS THERE "CODE FOR CODE'S SAKE"?
   Every change must directly serve acceptance criteria.
   If a change isn't tied to solving the problem — remove it.
   Drive-by refactoring = separate task, not part of this one.

Annotation Cycle

1. Claude drafts the plan
2. Ctrl+G — plan opens in editor
3. User adds > NOTE: annotations
4. Claude: "Address all notes, don't implement yet"
5. Repeat until no notes remain

Questions for User

• Only for real forks where there's a genuine decision to make
• Use AskUserQuestion with options
• For each question: recommend which option you think is best and why
• Don't ask the obvious

Final Plan

Create plans/YYYY-MM-DD-<name>.md (see templates/plan.md for full template with Challenge Log, phases, prompts)

→ /clear

Stage 4: Phased Implementation

Each phase = separate session, fresh context, feature branch.

Phases can be run in parallel via separate Claude Code sessions/terminals when they don't depend on each other. Check the plan for dependencies before parallelizing.

Guard phrase to start coding: Only begin implementation after the plan is finalized and all annotation notes are addressed. The trigger: "Implement Phase N according to plan."

Order within each phase:

1. Create/switch to feature branch: feature/<task>
2. Update status → in_progress
3. TDD: tests FIRST (red)
4. Implement: code to make tests pass (green)
5. Refactor (if needed)
6. Self-Audit (Stage 5)
7. Verification (Stage 6)
8. Impact Analysis (Stage 7)
9. Gates (see Gates section)
10. Commit (checkpoint)
11. Status → completed, write to Changelog
12. Handoff → /clear

Stage 5: Self-Audit (after each phase)

Mandatory BEFORE marking completed:

Check the phase implementation:

1. SPEC COMPLIANCE
   Open spec. Walk through every acceptance criterion.
   For each: implemented? Where exactly in code?
   If any not covered — finish it.

2. CHALLENGE THE SOLUTION
   Look at the written code with fresh eyes.
   Does this actually solve the problem from spec?
   Is there a simpler/more efficient way?
   Any "code for code's sake" — changes unrelated to the task?

Stage 6: Verification — Deep Bug Hunt

Not just linting. Thoughtful review with false-positive filtering.

Step 1: Find errors

Check ALL code from this phase for:
- Logic errors (wrong conditions, off-by-one, race conditions)
- Data handling (null/undefined, type mismatches)
- Security (injection, auth bypass, exposed secrets)
- Performance (N+1 queries, memory leaks, unnecessary re-renders)

Step 2: Verify bugs are REAL

For EACH found bug:
1. Is this a REAL bug or a false positive?
2. Can you prove this bug is reproducible?
3. If you can't prove it — it's NOT a bug. Don't touch it.

RULE: Don't fix code "for beauty" or "just in case".
Fix ONLY proven bugs that actually affect functionality.
Every "fix" without proof = risk of introducing a new bug.

Step 3: Logic and efficiency check

Final code cleanliness check:
- Logic: is the data flow correct from input to output?
- Efficiency: any redundant operations?
- Readability: is the code understandable without comments?
BUT: don't refactor "for beauty". Only if it affects correctness.

Stage 7: Impact Analysis — "Did we break anything?"

**The most underestimated stage. 75% o