claude-code - 💡(How to fix) Fix Verbosity defaults misfire when Claude writes its own durable instructions (memory, CLAUDE.md, skills) [1 participants]

Observation

Claude Code has explicit register tuning for chat output — terse, direct, no preamble, ~4-line CLI replies. That's the right tuning for ephemeral conversation a user reads once.

But there's no equivalent tuning for the other thing Claude writes: durable instructional content for itself — CLAUDE.md at project (./CLAUDE.md) and user/global (~/.claude/CLAUDE.md) level, custom agent definitions, skills, and any project-local instruction files Claude reads back across sessions. Anything Claude re-reads in future sessions.

With no register guidance for that case, Claude falls back to its general writing register: verbose, narrative, explanatory. That's the opposite failure mode from chat, but the same root cause — one register is governed, the other is not.

Why this matters: it's token economics, not style

The cost isn't aesthetic. Memory files, CLAUDE.md, and loaded skills enter the context window of every session. Bloat in those files is a recurring tax — paid on every boot, every tool call, every compaction.

A 200-line memory file written in chat-prose register vs. a directive register is a measurable, repeating cost across thousands of sessions. The same applies to skills: every loaded skill spends tokens, and skills written in chat-tuned prose carry transition phrases, restatements, and framing paragraphs that don't change behavior.

When Claude writes these files using its chat-output habits, it produces:

• Transition framing ("instead of X, do Y") — meaningful only to a reader who saw the prior version; pure noise to future Claude
• Restatement and meta-commentary ("the goal here is to…")
• Verbose narrative where a directive would do
• Cross-file duplication of rules already stated elsewhere

Each of these patterns is fine in chat. In a durable instruction file, they are recurring context cost with no behavioral payoff.

The ask

One of:

1. Documented best-practice guidance — a section in the Claude Code docs, or a starter CLAUDE.md template, that surfaces the chat-vs-instruction-file register distinction and gives users a small set of principles for writing durable instruction files (e.g., directives over narrative, no transition framing, no cross-file duplication, every line must change behavior or enable recognition).

2. A configurable verbosity/register profile that Claude applies when writing to specific file paths (CLAUDE.md, memory/, .claude/skills/, custom agent files), separate from the chat-output budget.

Option 1 is cheaper and probably sufficient — most users haven't noticed the mismatch yet because they treat memory/skill files as one-shot writes rather than living rule sets that compound in cost.

Background

I maintain a personal Claude Code project where memory files and skills are central to the agent's behavior. Over time I noticed the agent's own writes drifting toward chat-prose register — verbose framing, restatements, transition language — and ended up codifying a small set of context-engineering principles to push back:

• Every line must change behavior or enable recognition
• No cross-file duplication
• Directives over narratives
• No transition framing (the file carries the rule, git carries the diff)
• Operational details belong in skills/context files, not in always-loaded memory

Sharing this in case it's useful signal — the workaround works, but the underlying default is the thing worth surfacing. This is a case of using the agent to notice friction in the agent.

— Raphaël ([email protected])