Never Run claude /init

Summary

Matt Pocock argues against using Claude Code’s initialization command to generate a repository-wide CLAUDE.md or AGENTS.md. These files can add unnecessary instructions to every request, consume tokens, and become outdated as the codebase changes.

In a demonstration using a large repository built with React Router and Effect, the generated file included package scripts, architecture descriptions, and implementation details. Pocock says most of this information can be discovered directly from package.json, configuration files, source code, and the project’s directory structure. Keeping it in a global context file duplicates information and may burden tasks where it is irrelevant—for example, applying frontend-specific guidance during backend work.

An agent’s context window is shared among its system prompt, codebase research, implementation, and testing or debugging. Research and implementation needs vary by task, but global instructions are loaded upfront. Pocock also notes that models have a practical limit on how many instructions they can follow; irrelevant rules can constrain an agent before it begins.

Recommendations

• Keep repository-wide context files minimal. Include only information that is difficult to infer from the code and useful across many tasks.
• Use discoverable skills for specialized guidance or preferences, rather than loading them into every request. Examples include frontend reducer guidance and concise-writing preferences.
• Let agents inspect the codebase during their research phase instead of maintaining extensive documentation that may drift out of date.
• Include non-obvious environment details when they are broadly useful. One example from Pocock’s setup is: “You’re running WSL on Windows,” because the environment has special path considerations.

The video also refers to an article or study evaluating repository-level context files. It reports that unnecessary requirements can make tasks harder and that human-written context should contain only minimum requirements.

Main Speaker and Sources

• Main speaker: Matt Pocock
• Sources discussed: Pocock’s repository and Claude Code initialization output; an article or study on repository-level context files; and the codebase itself as a source of project information.