6 months of heavy Claude Code use: 4 prompt patterns that survived my notebook cleanup

Hardening Claude Code: Engineering Patterns for Production-Grade AI Assistance

Current Situation Analysis

The adoption of AI coding assistants like Claude Code has shifted from novelty to necessity, yet many engineering teams struggle to integrate these tools into production workflows reliably. The prevailing pain point is "chatbot drift": developers treat the AI as a conversational partner rather than a deterministic tool, resulting in output that is plausible but unreviewable. This leads to excessive manual verification, inconsistent code quality, and occasional critical regressions that negate the time savings of the tool.

This problem is often misunderstood as a limitation of the underlying model. In reality, the variability stems from prompt engineering practices. Analysis of six months of intensive Claude Code usage reveals that approximately 80% of initial prompts are discarded during workflow refinement. The surviving prompts share distinct engineering characteristics: explicit taxonomies, constrained output schemas, and mandatory safety gates.

Data from production incidents highlights the cost of unstructured AI interaction. A common failure mode involves "auto-apply" workflows where the AI modifies code without a proposal phase. In one documented case, an AI assistant removed an import deemed "unused" by static analysis, unaware that the module was referenced dynamically within a template string. The local build passed, but the staging deployment failed due to a missing bundle asset. Resolving this required a git bisect session that consumed significant engineering time. This incident underscores that without structural constraints, AI assistance introduces risk that outweighs velocity gains.

WOW Moment: Key Findings

The transition from ad-hoc prompting to engineered workflows yields measurable improvements in reliability and efficiency. The following comparison illustrates the impact of applying constraint-driven patterns versus traditional conversational prompting.

Approach	Review Overhead	Defect Leakage	Actionability	Blast Radius Visibility
Ad-hoc Chat	High	Medium	Low	None
Engineered Workflow	Low	Low	High	Explicit

Why this matters: The engineered approach transforms the AI from a text generator into a structured data producer. By enforcing taxonomies and safety gates, the review process shifts from reading prose to validating structured artifacts. This reduces cognitive load, enables automated validation steps, and ensures that the developer retains control over the commit history. The "blast radius" visibility allows teams to assess risk before code is modified, turning AI assistance into a predictable engineering lever rather than a variable.

Core Solution

To achieve production-grade reliability, prompt design must be treated as an engineering discipline. The solution involves three core patterns: constraint-driven scoping, taxonomy-enforced output, and propose-before-apply gates. These patterns can be implemented using TypeScript interfaces to define the contract between the developer and the AI, ensuring consistency across the team.

1. Constraint-Driven Scoping

Generic instructions produce generic output. Effective prompts must define the scope, constraints, and expected output shape explicitly. This reduces the search space for the model and forces a deterministic response structure.

Implementation: Define a RefactoringSpec interface that captures all necessary constraints. The prompt should reference this structure, ensuring the AI adheres to the defined boundaries.

// src/ai/specs/refactoring.spec.ts

export interface RefactoringSpec {
  target: {
    filePath: string;
    functionName: string;
    lineRange: { start: number; end: number };
  };
  constraints: {
    maxExtractionSize: number; // Lines of code
    preservePublicApi: boolean;
    requireTypeCheck: boolean;
  };
  output: {
    includeCallSites: boolean;
    includeClosedOverVars: boolean;
    requireApproval: boolean;
  };
}

export const extractHelperSpec: RefactoringSpec = {
  target: {
    filePath: "<TARGET_FILE>",
    functionName: "<TARGET_FUNCTION>",
    lineRange: { start: 0, end: 0 }, // AI to fill
  },
  constraints: {
    maxExtractionSize: 20,
    preservePublicApi: true,
    requireTypeCheck: true,
  },
  output: {
    includeCallSites: true,
    includeClosedOverVars: true,
    requireApproval: true,
  },
};

Rationale: By externalizing the spec, you create a reusable artifact. The prompt becomes a template that injects these constraints. This ensures that every refactoring request follows the same rigorous standard, regardless of who triggers it. The requireApproval flag enforces the safety gate pattern.

2. Taxonomy-Enforced Output

Unstructured text is unreviewable at scale. Prompts must mandate a classification taxonomy for findings. This allows developers to triage results efficiently, focusing only on high-confidence items.

Implementation: Define an enum for classification and require the AI to map findings to these categories.

// src/ai/taxonomies/audit.taxonomy.ts

export enum FindingCategory {
  CONFIRMED_ISSUE = "CONFIRMED_ISSUE",
  LIKELY_ISSUE = "LIKELY_ISSUE",
  FALSE_POSITIVE = "FALSE_POSITIVE",
  STYLE_VIOLATION = "STYLE_VIOLATION",
}

export interface AuditFinding {
  category: FindingCategory;
  location: { file: string; line: number };
  evidence: string;
  recommendation: string;
}

export type AuditReport = AuditFinding[];

Prompt Integration: The prompt should instruct the AI to output a JSON array conforming to AuditReport.

"Analyze the codebase for unused dependencies. Output a JSON array of AuditFinding objects. Classify each finding using FindingCategory. Include file:line for every location. Do not provide prose explanations; output only the structured report."

Rationale: Taxonomies enable automated filtering. A script can parse the JSON output and generate a summary report, highlighting only CONFIRMED_ISSUE items for immediate review. This reduces the time spent parsing AI output and minimizes the risk of missing critical findings buried in text.

3. Propose-Before-Apply Gates

Direct application of AI changes is a high-risk operation. The highest-ROI pattern is to mandate a proposal phase where the AI outputs the plan and waits for approval.

Implementation: Enforce a workflow step that separates analysis from execution.

// src/ai/workflows/safety-gate.ts

export interface ChangeProposal {
  id: string;
  description: string;
  files: Array<{ path: string; diff: string }>;
  blastRadius: {
    affectedTests: string[];
    affectedModules: string[];
    riskLevel: "LOW" | "MEDIUM" | "HIGH";
  };
  status: "PENDING" | "APPROVED" | "REJECTED";
}

export class SafetyGate {
  private proposals: Map<string, ChangeProposal> = new Map();

  submitProposal(proposal: ChangeProposal): void {
    this.proposals.set(proposal.id, proposal);
    console.log(`Proposal ${proposal.id} submitted. Awaiting approval.`);
    console.log(`Blast Radius: ${proposal.blastRadius.affectedModules.length} modules.`);
  }

  approve(id: string): boolean {
    const proposal = this.proposals.get(id);
    if (!proposal || proposal.status !== "PENDING") return false;
    proposal.status = "APPROVED";
    return true;
  }
}

Rationale: The SafetyGate class represents the mental model for the workflow. The prompt must include a directive: "Do not apply changes. Output a ChangeProposal object and wait for the APPROVED signal." This extra round-trip cost is negligible compared to the time saved by avoiding regressions. It also forces the AI to articulate the blast radius, providing the developer with context needed to make an informed decision.

Pitfall Guide

Even with structured patterns, teams encounter common mistakes. The following pitfalls are derived from production experience and should be avoided.

Pitfall	Explanation	Fix
The "Do Something" Trap	Using vague verbs like "fix" or "improve" without defining success criteria. The AI guesses the intent, leading to inconsistent results.	Replace vague verbs with precise actions. Define the output format and constraints explicitly. Use RefactoringSpec to bound the request.
Unstructured Triage	Allowing the AI to output free-text findings. This requires manual reading and interpretation, negating efficiency gains.	Enforce a taxonomy. Require JSON output with fixed categories. Use FindingCategory to enable automated filtering.
Blind Auto-Application	Configuring the AI to apply changes immediately. This bypasses review and increases the risk of introducing regressions.	Implement a SafetyGate. Always require a proposal phase. Use requireApproval: true in specs.
Citation Drift	Findings lack precise locations. The developer must search for the issue, wasting time.	Mandate file:line format for all findings. Validate that every AuditFinding includes a location object.
Template Hoarding	Saving one-shot prompts as reusable templates. This bloats the prompt library with low-value artifacts.	Delete prompts used only once. Keep only patterns that are reused across multiple tasks. Maintain a lean prompt set.
Dynamic Graph Blind Spots	AI misses dynamic references (e.g., template strings, reflection) and removes "unused" code.	Explicitly warn the AI about dynamic references. Add a constraint: "Check for dynamic imports and template references before removing code."
Missing Anti-Pattern Registry	Repeating mistakes because failed prompts are not tracked.	Maintain an ANTI_PATTERNS.md file. Document prompts that produced incorrect output and the reason for failure. Review this file periodically.

Production Bundle

This section provides actionable artifacts to implement the engineered workflow immediately.

Action Checklist

• Define Taxonomies: Create audit.taxonomy.ts with enums for all finding categories relevant to your project.
• Implement Safety Gates: Add a SafetyGate class or workflow step that requires approval before applying changes.
• Enforce Citations: Update all prompts to require file:line format. Validate output includes location objects.
• Prune Prompt Library: Review existing prompts. Delete any that lack explicit taxonomies or safety gates. Aim to reduce volume by ~80%.
• Create Anti-Patterns File: Initialize ANTI_PATTERNS.md. Document any prompts that have caused issues and the mitigation strategy.
• Validate Type Checks: Ensure refactoring prompts include a step to run the type-checker and report errors.
• Test Dynamic References: Add a constraint to prompts handling imports to check for dynamic usage patterns.

Decision Matrix

Use this matrix to determine the appropriate approach based on the task context.

Scenario	Recommended Approach	Why	Cost Impact
Refactoring Core Logic	Engineered Workflow	High risk of regression. Requires precise scoping and safety gates.	Low (prevents expensive rollbacks)
Exploratory Debugging	Ad-hoc Chat	Low risk. Goal is insight, not code change. Speed is priority.	Minimal
Dependency Audit	Taxonomy-Enforced	Large volume of findings. Structured output enables triage and automation.	Low (saves review time)
Documentation Update	Constrained Prompt	Moderate risk. Requires accuracy but less structural rigor than code changes.	Low
One-Off Script	Conversational	Single use. No need for reusable template.	None

Configuration Template

Add this configuration to your CLAUDE.md or project root to enforce standards across the team.

# CLAUDE.md - Engineering Standards

## Output Requirements
- All findings must be classified using `FindingCategory`.
- All locations must use `file:line` format.
- No prose explanations in structured outputs.

## Safety Protocols
- NEVER apply changes without explicit approval.
- Always output a `ChangeProposal` for code modifications.
- Include `blastRadius` analysis in proposals.

## Anti-Patterns
- Do not remove imports without checking dynamic references.
- Do not assume static analysis covers all usage patterns.
- Do not output unstructured text for audit tasks.

Quick Start Guide

1. Initialize Structure: Create src/ai/specs/ and src/ai/taxonomies/. Add the interfaces and enums from the Core Solution.
2. Configure Safety: Add the SafetyGate logic to your workflow scripts or instruct Claude Code to use the proposal pattern by default.
3. Test a Refactoring: Run a refactoring task using extractHelperSpec. Verify the output includes call sites, closed-over variables, and a proposal for approval.
4. Audit Findings: Run an audit task. Parse the JSON output and filter by CONFIRMED_ISSUE. Verify all findings have valid file:line citations.
5. Review and Iterate: Check ANTI_PATTERNS.md for known issues. Update prompts based on results. Prune any prompts that do not meet the standards.

By treating prompt design as an engineering discipline, teams can unlock the full potential of AI coding assistants while maintaining the reliability and safety required for production environments. The patterns outlined here provide a foundation for building robust, scalable AI workflows that deliver consistent value.