Architecture

Architecture: four channels, four jobs

Claude Code offers several places to put an instruction. Choosing the right one for each rule is the whole design.

The channels

1. CLAUDE.md, the always-loaded rules

~/.claude/CLAUDE.md is read at the start of every session, whatever the project. It holds what is true all the time:

• the adaptive teaching profile
• the visual clarity rules
• the git conventions
• the honesty rules
• the answer format
• the token economy guidance

A project can add its own CLAUDE.md at its root, which layers on top of the global one.

Criterion for putting a rule here: it applies whatever you are working on, and it is short. This file is paid for on every single request, so every line has to earn its place.

2. The skills, loaded on demand

Each skill is a directory under ~/.claude/skills/ holding a SKILL.md with a name and a description. Claude Code reads those descriptions and loads the full skill only when the subject matches.

That is the important difference with a rule in CLAUDE.md: a skill can run to three hundred lines because you only pay for it when it is relevant. All 29 together would never fit in a permanent context.

Criterion: bulky, specialised knowledge tied to one domain or one workflow.

3. settings.json, what the harness enforces

This is not advice to the model, it is configuration the tool obeys. It carries the model and effort level, the theme, and above all the permissions:

"deny": [
  "Bash(gh repo delete:*)",
  "Bash(gh repo edit:*)",
  "Bash(git push --force:*)",
  "Bash(git push -f:*)"
]

Criterion: anything where a polite instruction is not good enough. A rule in CLAUDE.md asking not to force-push is a wish; a deny entry is a wall. Destructive and irreversible commands belong here, not in prose.

Note that defaultMode is set to auto, which lets ordinary work proceed without a prompt on every call. The deny list is what makes that comfortable rather than reckless.

4. The plugin, which shapes the output

settings.json declares the i-have-adhd marketplace and enables the plugin. It registers its own hooks and shapes how answers are written.

Criterion: behaviour that has to be reinjected constantly, close to the end of the context, where model attention is highest. That is precisely what a rule at the top of CLAUDE.md cannot do once a session grows long.

Why the split matters

The question to ask for any rule: what happens when it is forgotten or ignored?

Consequence	Where it belongs
Destructive and irreversible	settings.json deny list
Silent or expensive, and must never drift	the plugin and its hooks
Always relevant, cheap to state	CLAUDE.md
Bulky, and only sometimes relevant	a skill

It is the same reasoning as in infrastructure: what is critical goes into the most reliable layer, what is bulky goes into the cheapest one.

Where the hooks directory went

hooks/ ships with nothing but a CommonJS manifest. An earlier version of this configuration carried its own hook scripts and a custom status line. They were removed when the output shaping moved to the i-have-adhd plugin, which registers its own hooks and does the same job without a pile of local scripts to maintain.

The directory stays because Claude Code expects it and because project-specific hooks may land there later.