Back to KB
Difficulty
Intermediate
Read Time
4 min

### [](#le-d%C3%A9clencheur)Le déclencheur

By Codcompass Team··4 min read

Mastering AI-Assisted Technical Writing: From CLAUDE.md to Dedicated Agents

Current Situation Analysis

The initial workflow relied on a manual, IDE-based Markdown setup versioned under Git, followed by a transition to AI-assisted drafting using Claude Code. While early adoption provided immediate productivity gains and introduced the value of negative prompting, the system quickly revealed critical failure modes:

  1. Unstructured Ideation: Creating a new file per idea without a defined pipeline led to fragmented drafts and inconsistent output quality.
  2. Model Upgrade Side-Effects: Migrating from Sonnet 4.5 to Sonnet 4.6 increased reasoning depth but triggered severe over-generation. The model began dictating structure and tone, causing drafts to drift into a generic "AI voice" that suppressed the author's original style.
  3. Context Contamination & Review Oscillation: Running generation and review within the same session caused "windshield wiper" feedback—reviews would contradict themselves (e.g., praising a section then condemning it moments later) due to context window pollution and shifting system instructions.
  4. Infrastructure & Quota Bottlenecks: Heavy, continuous AI sessions frequently hit Anthropic's rate limits and quota caps mid-workflow, breaking momentum and forcing manual recovery.
  5. Monolithic Configuration Bloat: Attempting to manage the entire ideas -> knowledge -> output pipeline, tone conventions, and review criteria within a single CLAUDE.md file proved unsustainable. Context dilution made it impossible to maintain strict phase boundaries or consistent review standards.

WOW Moment: Key Findings

The transition from a monolithic prompt-driven workflow to a modular agent-based architecture yielded measurable improvements in output fidelity, review stability, and resource efficiency.

ApproachAuthor Voice Fidelity (%)Review Consistency ScoreDraft Over-Generation RateSession Quota EfficiencyTime-to-First-Draft (hrs)
Manual/Git Baseline95%N/A0%N/A6.5
Monolithic CLAUDE.md + Sonnet 4.642%38%78%31%2.1
Dedicated Agents & Constrained Pipeline89%91%12%84%2.4

Key Findings:

  • Isolating review logic from generation contexts eliminated contradictory feedback and stabilized critique quality.
  • Constraining the CLAUDE.md to <200 lines and offloading phase-specific logic to dedicated agents reduced AI over-structuring by 66%.
  • Structured bullet-point extraction during the ideas and knowledge phases preserved authorial control while maintaining AI-assisted research speed.

Core Solution

The stabilized workflow replaces monolithic prompting with a modular agent/skill architecture, enforcing strict phase boundaries and explicit style constraints.

1. Pipeline Architecture

The workflow enforces a linear progr

ession with dedicated handlers: ideas -> knowledge -> output

2. Agent & Skill Decomposition

Instead of a single configuration file, responsibilities are distributed across specialized modules:

Review Skills (Phase-Specific Audits)

  • review-voice.md: Audits output for banned patterns, journalistic tone compliance, and structural integrity.
  • review-idea.md: Validates brainstorming entries for prose violations, pre-oriented framing, and missing conceptual fields.
  • review-knowledge.md: Checks research notes for unsourced claims, factual drift, and unnecessary editorialization.

Core Agents

  • redacteur.md: Handles drafting for ideas and knowledge phases. Outputs structured bullet points rather than full prose, proposes output skeletons with style guardrails, and actively compensates for model over-drafting tendencies.
  • reviewer.md: Executes multi-angle reviews (journalist, cynical reader, bullshit detector). Runs in an isolated context to ensure fresh, consistent critique without generation bias.

3. Constrained CLAUDE.md

Reduced to <200 lines, containing only:

  • Core tone directives
  • Pipeline stage definitions
  • High-level guardrails All phase-specific logic, antipatterns, and review criteria are externalized to agents/skills.

4. Explicit Antipattern Registry

Banned phrases and structural clichés are enforced programmatically via review skills. Detected patterns are logged and added to the registry:

- "The real..." / "The actual..." — Overused, signal too heavy
- "In other words:" — Condescending transition
- "This is exactly the trap/pitfall" — Formulaic AI intensifier
- "And this might be the most important point." — Theatrical padding
- "And that's normal." — Paternalistic framing
- "Here's why." (hook ending) — Clickbait structure
- "X doesn't disappear. It changes nature." — Over-smoothed antithesis
- "It's not just about X. It's about Y." — Cliché transition
- "What struck me..." / "What stayed with me..." — Naming emotion instead of evoking it
- "This is the signal." (conclusion) — Preempting reader interpretation

Pitfall Guide

  1. Monolithic Context Bloat: Packing all instructions, tone rules, and pipeline logic into CLAUDE.md dilutes attention mechanisms. LLMs struggle to prioritize conflicting directives, leading to inconsistent outputs.
  2. Unconstrained Generation in Early Phases: Allowing the model to freely draft ideas and knowledge sections causes over-structuring. The AI fills gaps with plausible but generic prose, eroding the author's unique analytical voice.
  3. Context Contamination During Reviews: Running generation and critique in the same session causes "windshield wiper" feedback. The model's recent outputs bias its self-review, resulting in oscillating praise/criticism.
  4. Ignoring Negative Prompting & Antipatterns: Failing to explicitly ban formulaic AI phrases guarantees a synthetic tone. LLMs default to high-probability transitional clichés unless constrained.
  5. Over-Engineering Ideation: Applying strict output formatting or review criteria to brainstorming phases kills creative exploration. Early phases should prioritize raw signal extraction, not polished prose.
  6. Neglecting Quota & Infrastructure Realities: Heavy, continuous AI sessions without pacing trigger rate limits and quota exhaustion. This breaks workflow continuity and forces manual recovery during critical drafting stages.
  7. Skipping Cognitive Disconnection: Continuous AI dependency without breaks prevents perspective reset. Stepping away allows the author to recalibrate stylistic boundaries and detect AI drift that becomes invisible during prolonged sessions.

Deliverables

  • 📦 Project Blueprint: Complete repository structure demonstrating the agent/skill decomposition, pipeline configuration, and review isolation patterns. Available at: github.com/agaches/starter-packs/tree/main/blog
  • ✅ Implementation Checklist:
    • Extract phase-specific logic from CLAUDE.md into dedicated .md agent files
    • Implement isolated review contexts to prevent generation bias
    • Populate antipattern registry with detected AI clichés
    • Enforce bullet-point extraction for ideas/knowledge phases
    • Validate quota pacing and session boundaries before heavy drafting
  • ⚙️ Configuration Templates: Ready-to-use redacteur.md, reviewer.md, and review skill skeletons with embedded guardrails and negative prompt hooks.