Alex Wang's Post

Alex Wang · article · 2026-04-16 Reader 🖥️

Agent Harness Agent Skills Claude Code Agent Context Files (CLAUDE.md / AGENTS.md)Hooks

Claude Code becomes more reliable when you move recurring, deterministic, and structural concerns out of ad-hoc prompts and into the environment (CLAUDE.md, skills, hooks, plan mode).

practical · expository — A concise listicle of workflow advice for Claude Code users, structured as four numbered habits with a unifying insight at the end. No sustained argument or narrative -- pure practitioner prescription.

Structure

Part	Role
Habit 1: Keep CLAUDE.md focused	Establishes what should and should not live in the main context file
Habit 2: Use Plan Mode for bigger changes	Advises a two-phase (inspect-then-act) workflow for complex edits
Habit 3: Turn repeated prompts into skills	Identifies prompt repetition as a signal to create reusable abstractions
Habit 4: Use hooks for deterministic tasks	Delegates formatting, validation, and guardrails to system-level automation
Closing synthesis	Restates the unifying principle: shift from repeated prompting to structure
Course promotion	Commercial call-to-action; does not contribute to the argument

Key terms

CLAUDE.md Agent Context Files (CLAUDE.md / AGENTS.md)
A project-level context file read by Claude Code on startup; should contain stable context (architecture, conventions) rather than procedural instructions
Plan Mode Claude Code
A Claude Code mode where the model inspects and proposes changes before executing them, reducing risk for multi-file edits
skills Agent Skills
Reusable, named prompt templates or procedures that replace ad-hoc repeated instructions
hooks Hooks
System-level automations triggered deterministically (e.g., on commit, on save) rather than relying on the model to remember
environment Agent Harness
The configuration and tooling layer surrounding Claude Code (CLAUDE.md, skills, hooks, plan mode) as opposed to the prompt itself

Propositions

explicitcontestedCLAUDE.md should contain stable project context (architecture, conventions, commands), not procedural playbooks.
extends ←How Claude Code works in large codebases: Best practices and where to start · p1 — Both agree CLAUDE.md should hold stable project context rather than procedure; this article adds the large-scale elaboration (root-vs-subdirectory layering, lean root file) of the same principle.
contradicts ←Three more static code analysis sensors · p4 — Bockeler claims enforceable dependency rules can replace the prose architecture guide, while Wang says stable architecture context belongs in CLAUDE.md markdown.
explicitestablishedRepeatable procedures, checklists, and playbooks belong in a separate mechanism (skills), not in CLAUDE.md.
supports ←How Claude Code works in large codebases: Best practices and where to start · p5 — Both agree repeatable procedures belong in skills, not CLAUDE.md, with this article adding the organizational rationale (context bloat across dozens of task types at scale) for why that separation matters more as codebases grow.
supports ←Zero to Agent in 30 Minutes: Build a Workflow Agent with John Berryman · p8 — Berryman's tip to build self-checking checklists into skills is a concrete instance of the corpus principle that repeatable procedures/checklists/playbooks belong in skills, not scattered elsewhere.
explicitMulti-file edits and refactors are safer when Claude inspects and plans before touching code.
explicitdevelopedIf you repeatedly type the same instructions, the workflow should become a reusable skill.
refines ←Agent Skills · p4 — Wang says repeated instructions should become skills; Osmani specifies what makes a skill actually work — a workflow with steps and exit criteria, not an essay of best practices.
explicitcorroboratedDeterministic concerns (formatting, validation, guardrails) are better handled by system hooks than by hoping the model remembers.
supports ←Google Introduces Middleware Architecture for Genkit Applications · p1 — Genkit's middleware thesis matches Wang's hooks advice: reliability and guardrails belong in a programmable system layer around the model, not in prompts.
explicitestablishedReliability improves when structure is moved from the prompt into the environment.
supports ←Three more static code analysis sensors · p16 — Encoding design intent as enforceable tool-config invariants is a concrete case of moving structure from the prompt into the environment to gain reliability.
supports ←Google Introduces Middleware Architecture for Genkit Applications · p1 — Google productizes the same principle: reliability and safety belong in a programmable layer around model and tool calls, not in prompts — structure moved from prompt into environment.
implicitcorroboratedLLM agents cannot be relied upon to consistently remember and apply deterministic rules without system-level enforcement.
supports ←Portal by Spotify cut my Claude Code token usage by 90% · p5 — A concrete instance of the general claim: an advisory routing rule in CLAUDE.md proved ignorable, which is what motivated moving enforcement into a hook.
implicitThere is a maturity progression from ad-hoc prompting to structured environment configuration.

Arguments

Claude Code becomes more reliable when you structure the environment rather than relying on prompt content alone.

Explicit premises:

CLAUDE.md works best for stable context, not instruction dumps (P1)
Repeated prompts should become skills (P4)
Deterministic tasks should be hooks, not model memory (P5)
Plan Mode reduces risk for complex changes (P3)

Implicit premises:

LLM outputs are non-deterministic, so deterministic guarantees require non-LLM mechanisms (P7)
Prompt bloat degrades model performance

Narratives

Questions addressed

✅ How do you make Claude Code more reliable in practice?
✅ What belongs in CLAUDE.md versus elsewhere?

Gaps

incompleteNo evidence or examples are provided for any of the four habits. The claims are presented as practitioner wisdom without empirical support, before-after comparisons, or concrete scenarios showing failure modes.
incompleteThe distinction between what belongs in CLAUDE.md vs. skills vs. hooks is stated but not precisely bounded. A convention that is also a checklist could plausibly go in either place.
uninformedThe post does not address trade-offs or costs of the recommended approach -- e.g., the overhead of maintaining skills and hooks, the risk of over-engineering small projects, or when ad-hoc prompting is actually sufficient.
incompleteThe post ends with a course promotion, raising the question of whether the advice is calibrated to be genuinely complete or deliberately leaves gaps to motivate enrolment.