Should You Use /init to Generate CLAUDE.md or AGENTS.md?

The /init command can generate a useful-looking CLAUDE.md or AGENTS.md file by scanning your codebase and summarizing commands, architecture, and conventions. But useful-looking does not always mean useful enough to load into every agent session.

Intro

When you run /init, your coding agent explores the project and writes a memory file with guidance about how the repository works. If you are new to the project, this can be helpful as a high-level overview.

The more important question is whether all that information should be loaded automatically before every single task.

In the example from the video, a minimal memory file loaded around 415 tokens. The file generated by /init loaded around 3.7 thousand tokens. With large context windows, this is not mainly about saving a few thousand tokens. The real question is what those extra tokens are buying you.

If the generated content contains durable guidance that helps the agent in almost every session, it belongs in the memory file. But if it mostly contains generic commands, architecture snapshots, or information the agent can infer from the codebase when needed, it becomes noise.

What Belongs in a Memory File

A line in CLAUDE.md or AGENTS.md should not survive just because it might be useful someday. It should survive because it is useful enough to read every time, before the agent even knows what task it is about to work on.

The video uses a real Flutter app as the example. The repository root is a thin shell, and the actual Flutter app lives inside a folio_tracker/ subdirectory. In the past, agents had looked for pubspec.yaml in the wrong place.

That is exactly the kind of information that belongs in a top-level memory file:

It is durable.
It applies to almost every task.
It prevents a real mistake the agent might otherwise make.

For that project, the minimal useful memory file is essentially one line telling the agent where the Flutter app lives. Everything else has to clear the same bar.

Keep, Remove, or Move

To evaluate the generated file, the video uses a simple three-way test: keep, remove, or move.

Keep means the line belongs in every session. Remove means the line is generic, likely to become stale, or easy to infer from source files. Move means the information is useful, but only for certain tasks, so it should live somewhere else.

Many generated sections fail this test. Headings like CLAUDE.md and boilerplate explanations of what the file is for do not add useful guidance. Common commands such as flutter pub get, flutter run, flutter analyze, and flutter test are standard enough that the agent can already infer them.

Even more specific command notes are not always worth loading every time. For example, a Sentry-specific run command can be useful, but only when working on Sentry-related behavior. Formatting settings, build runner commands, Firebase deploy steps, and similar details usually have source-of-truth files the agent can inspect when needed.

The important distinction is not whether a line is correct. It is whether the agent should always know it before the task is known.

Architecture Snapshots Are Often Better Elsewhere

The generated file also includes architecture notes: data, domain, and presentation layers; Riverpod usage; Drift code generation; folder descriptions; database connection patterns; testing conventions; Sentry setup; and project-specific constraints.

Some of this information is genuinely useful. But much of it is a snapshot of the current project rather than durable always-on guidance.

An agent can usually discover folder structure, package usage, test organization, and configuration details by exploring the codebase. And because architecture notes can change over time, keeping a large copy inside CLAUDE.md or AGENTS.md creates another place that can become stale.

For information like cross-platform database connection patterns, import and export behavior, testing structure, or Sentry setup, the better destination is often a dedicated project document that can be loaded on demand.

Skills vs Project Docs

When generated content is useful but does not belong in the memory file, there are two main places it can go: skills or project docs.

Skills are reusable across projects. They are a good fit for steering instructions, checklists, workflows, and procedures. For example, testing workflows or Flutter-specific implementation patterns can live in skills and be loaded only when relevant.

Project docs are for project-specific knowledge. These can explain the folder structure, architecture, database behavior, import and export rules, frontend patterns, or other details that are useful for some tasks but not every task.

A practical rule is:

If it tells the agent how to work, consider a skill.
If it explains how this project works, consider a project document.

This keeps the always-loaded memory file small while still making important knowledge available when needed.

Be Careful with @ Imports

One useful pattern is to keep a short table of contents in CLAUDE.md or AGENTS.md that lists relevant project docs.

But there is an important caveat: do not use @ references in the memory file unless you really want those files expanded and loaded automatically at the start of every session.

Plain references can point the agent toward useful documents without importing them immediately. @ imports, on the other hand, increase the default context because those files are loaded along with the memory file.

The goal is to make knowledge discoverable without forcing every session to read everything.

Practical Takeaways

The /init command can still be useful, but mostly as a project exploration tool. It gives you a first draft of what the agent found, and you can then decide what deserves to stay.

For a cleaner setup:

Keep CLAUDE.md or AGENTS.md minimal.
Include only guidance that is always relevant.
Remove generic commands the agent can infer.
Move reusable workflows into skills.
Move project-specific explanations into project docs.
Reference project docs without automatically importing them into memory.

When moving knowledge out of the memory file, remember that you still own that knowledge. Generated docs should be reviewed, refined, and kept in sync with the codebase if you want them to remain useful.

Summary

You can use /init to generate a project summary, but in many cases you are better off writing a minimal memory file yourself.

The best CLAUDE.md or AGENTS.md file is not the one with the most information. It is the one that contains the right information: durable, task-independent guidance that helps the agent avoid real mistakes in every session.

Everything else should be removed, moved to reusable skills, or stored in project docs that can be loaded deliberately. This keeps your default context clean while preserving access to the guidance that matters.

Happy coding!