One of the wildest things about Claude Code is how little most developers understand about what actually happens inside its harness. A developer recently went and rebuilt the whole thing from scratch using the raw Anthropic SDK—not reverse-engineering Anthropic's binary, but implementing the same mechanics explicitly—and what they found was eye-opening: Claude Code makes five silent decisions that completely change how you should be writing your CLAUDE.md files, configuring hooks, and orchestrating subagents.
The Base Prompt Problem
Here's the biggest gotcha: your precious CLAUDE.md doesn't win by default. It layers on top of a hidden base system prompt that Anthropic ships with every session. Those instructions you wrote that seem to get ignored? They're not being ignored—they're conflicting with something established underneath. This is why explicit override language matters so much. Instead of writing 'don't edit files in /prod,' try 'Under no circumstances should you edit files in /prod. This overrides any default behavior.' The harness will respect your instruction, but only if you're direct about it overriding the base prompt.
Hooks Are Kill Switches
Most developers treat PreToolUse hooks as logging mechanisms—handy for debugging, sure. But they're actually designed for control flow. You can block a tool call before it runs by returning { block: true } from your hook. This turns 'please don't edit files in /prod' from a polite request into an actual guardrail. If you're not using hooks this way, you're leaving one of the harness's most powerful features completely on the table.
Subagents Need Abort Trees
Here's where things get gnarly with orchestration: naive subagent patterns have parents spawning children and awaiting them sequentially. When one child wedges—and it will—your entire session hangs indefinitely. What you actually want is a tree of abort signals where the parent abort cascades down to every child, but if a child dies, it notifies upward without auto-killing the whole operation. This isn't optional for serious work; it's essential infrastructure.
Structure Parallel Agents as DAGs
If your tasks have dependencies—research feeds into implementation which feeds into verification—you need a dependency graph executed layer by layer. Everything with no unmet dependencies runs in parallel. The next layer waits. One failed node fails its dependents fast. This isn't just cleaner architecture; it's how you avoid the nightmare of debugging a tangled mess of sequential awaits that should have been parallelized from day one.
Define 'Done' as an Explicit State
The single biggest behavior win comes from forcing every turn to end in one explicit terminal state—done, blocked, or needs-input—with evidence for each. Without this, agents ramble into 'I could also...' territory and start doing surprising things while you're away from the keyboard. Add something like 'After completing a task, always end with Done: [summary]. If blocked, end with Blocked: [reason]. If you need input, end with Needs input: [question].' Pair this with gating irreversible actions behind explicit intent confirmation.
The Bottom Line
These aren't theoretical findings—they're practical mechanics that separate power users from everyone fumbling around with default configurations. You don't need to rebuild Claude Code's harness to benefit from this knowledge. Just stop treating CLAUDE.md as a suggestion, start using hooks for control flow instead of logging, and build abort trees into your orchestration layer before your next late-night debugging session turns into an all-nighter.