The Trap of "Isolated Success" in AI Coding
The most significant risk in AI-assisted development isn't a syntax error or a logic bug; it is the creation of code that is "correct but misplaced" . Boris Tane, who joined Cloudflare after his serverless observability platform, Baselime, was acquired, notes that AI often lacks a "global" understanding of a codebase .
Common "isolated failures" include:
Implementing a new feature while completely ignoring an existing internal cache layer .
Creating database migrations that violate existing ORM (Object-Relational Mapping) conventions .
Duplicating logic that already exists elsewhere in the system because the AI didn't "see" it .
When these errors occur, the developer often spends more time rolling back and fixing the "perfect" but "wrong" code than they would have spent writing it manually .
The 4-Phase Claude Code Workflow
To solve this, Tane suggests a rigorous pipeline that treats the AI like a highly efficient construction crew and the developer like the lead architect .
1. Research: Forcing Deep Comprehension
Before asking for a solution, force Claude to read the entire relevant directory . The goal is to produce a research.md file that serves as a "review surface" for the human architect .
Instructional Keywords: Use strong modifiers like "deeply," "in great detail," and "intricacies" .
The Goal: Claude should explain how the current system works, its dependencies, and its edge cases before proposing changes .
Validation: If the research.md contains errors about how your system functions, the subsequent code will be fundamentally flawed .
2. Planning: Defining the Specification
Once the research is validated, the AI creates a plan.md . This is not a vague vision statement; it is a technical blueprint.
A high-quality plan must include:
Specific File Paths: Exactly which files will be modified .
Code Snippets: Demonstrations of the proposed logic changes .
Trade-offs: A discussion of why a specific approach was chosen over others .
Reference Implementations: Tane suggests providing an example of a similar feature from an open-source project to give the AI a "concrete anchor" .
3. Annotation: The Human-in-the-Loop Feedback
This is the most critical stage. Instead of arguing with the AI in a chat window, the developer opens the plan.md in their editor and adds inline annotations .
Shared Mutable State: The markdown file acts as a shared state between the human and the AI .
Specific Corrections: The developer can veto over-engineering, enforce project-specific naming conventions, or protect specific API signatures that must not change .
Iteration: This cycle of annotation and plan updates may repeat 1 to 6 times until the plan is "perfect" .
4. Implementation: Making Execution "Boring"
When the plan is finally approved, the implementation should be mechanical and "boring" .
The Instruction: "Implement everything. Do not stop until every task is marked complete in the plan" .
The Guardrails: Instruct Claude to run type-checks ( typecheck ) continuously and avoid using any or unknown types to maintain code quality .
The Rollback Rule: If the AI starts veering off-course, do not try to patch the mistake. Roll back the Git changes entirely and restart with a narrower scope .
Comparison: Traditional Prompting vs. The Tane Workflow
How to Stay in the "Pilot's Seat"
A core tenet of this workflow is that the human retains all decision-making power . Tane identifies four specific ways to guide the AI during the planning phase:
Pick and Choose: Select only the parts of an AI suggestion that add value while discarding over-engineered components .
Trim Scope: Explicitly remove "nice-to-have" features that aren't necessary for the current task .
Protect Interfaces: Set hard constraints on function signatures and public APIs to ensure backward compatibility .
Override Technical Choices: Force the AI to use specific libraries or internal methods it might have overlooked .
FAQ: Optimizing Claude Code for Production
Q: Why shouldn't I use the built-in "Plan Mode" in Claude Code? A: Boris Tane prefers using a dedicated plan.md file because it can be edited, annotated, and saved as a permanent record within the project . Built-in modes often lack the persistence and "shared state" benefits of a local markdown file .
Q: Does the AI lose context in long sessions? A: While many fear context degradation, Tane argues that keeping research, planning, and implementation in one long session is actually beneficial . The AI builds a deep understanding during the research phase that remains valuable during implementation .
Q: What is the most common reason for an AI coding failure? A: It is the "expensive failure mode" of implementation in isolation . The AI creates code that is syntactically perfect but breaks the surrounding system's established patterns .
Q: How do I handle bugs during the implementation phase? A: Use short, direct feedback like "You missed a specific function" or "This UI element needs a 2px gap" . If the error is systemic, roll back to the last clean Git state and refine the plan .
