keepcalculator

06 Numbers and Powers

Claude Code Init: How to Give It a Useful Project

Card No. 06·75773 · Updated · Standard formula, shown below

Claude Code’s init command sets up a project so Claude can understand its structure, conventions, and commands. This guide shows you how to run it effectively to get the most useful setup for your codebase.

What You’ll Need

  • A terminal with Claude Code installed (e.g., via npm or native installer).
  • An existing project directory you want to work in—it can be empty or have code.
  • Basic familiarity with your project’s build, test, and run commands.

Step-by-Step

  1. Open your project root. Navigate to the top-level folder of your project in the terminal. Claude Code’s init creates files relative to this directory, so starting at the root is essential.
  2. Run the init command. Type claude init and press Enter. If you’re using a specific model or want to avoid interactive prompts, you can add flags like --model sonnet or --yes to accept defaults.
  3. Answer the prompts. Claude will ask a series of questions about your project: the primary language, build system, test runner, and how you typically run the app. Be as specific as possible—these answers shape the generated configuration.
  4. Review the generated files. After the prompts, Claude creates a CLAUDE.md file (or updates it) and sometimes a .claude/ directory. Open CLAUDE.md to see what it contains: project overview, commands, and guidelines you provided.
  5. Edit the file for accuracy. The generated CLAUDE.md may have placeholders or mistakes. Correct any command paths, add missing context, and remove anything that’s wrong. This file is the core of what Claude uses later, so make it precise.
  6. Add project-specific details. Include things like: how to install dependencies, how to run tests, how to lint, how to start a dev server, and any architectural notes (e.g., “frontend is in src/, backend in api/“). The more context you give, the better Claude can help.
  7. Commit the changes. Once you’re happy with CLAUDE.md, commit it to version control. This ensures the setup is shared with your team and persists across sessions.
  8. Test it. Start a new Claude Code session in the same directory and ask a simple question like “How do I run the tests?” or “What’s the project structure?” Claude should answer using the info you provided. If not, refine the file.

Common Mistakes

  • Running init from a subdirectory. If you run claude init in src/ instead of the root, the generated files may be misplaced or miss the whole project context.
  • Skipping the prompts. Using --yes without reviewing what it accepts can lead to a generic CLAUDE.md that doesn’t reflect your actual workflow.
  • Leaving default values. If you don’t correct the initial answers, Claude might assume wrong commands (e.g., npm test when you use yarn test).
  • Not updating the file later. When your project changes (new build tool, different test framework), the CLAUDE.md becomes stale. Update it regularly.
  • Overloading with irrelevant info. Including every minor detail can dilute the important instructions. Keep it concise and focused on what Claude needs to assist effectively.

Tips

  • Use the interactive mode first. Even if you plan to edit manually, answering the prompts gives Claude a baseline to generate a more tailored file.
  • Include examples. Show a sample command or a snippet of code style in CLAUDE.md to clarify expectations.
  • Mention environment variables. If your project needs specific env vars to run, list them (without secrets) so Claude can warn you if they’re missing.
  • Keep it versioned. Store CLAUDE.md in your repo so all team members benefit from the same setup.
  • Use subdirectories for large projects. If you have a monorepo, you can place CLAUDE.md files in subdirectories to give context-specific instructions.

Troubleshooting

Init doesn’t create anything. Make sure you’re in a writable directory and that Claude Code has permission to create files. Check if a CLAUDE.md already exists—if so, init may ask to overwrite it.

The generated file is empty or minimal. This can happen if you skipped the prompts or provided very little info. Run claude init again and answer thoroughly, or manually add the missing sections.

Claude ignores the instructions. Ensure the file is named exactly CLAUDE.md (case-sensitive) and is in the project root. Also, check that you’re starting Claude Code from that same directory—if you’re in a subfolder, Claude may not find the root file.

Commands in CLAUDE.md fail. Verify the commands are correct for your environment. For example, if you use python but the system uses python3, update the file.

You accidentally deleted the file. Run claude init again to recreate it, or restore from version control if you committed it.

Frequently Asked Questions

Q: Do I need to run claude init for every project?
A: Yes, each project benefits from its own CLAUDE.md because the structure and commands differ. It’s a one-time setup per project (unless you change things).

Q: Can I use claude init on an empty directory?
A: Absolutely. It will create a basic CLAUDE.md with whatever you specify. You can always expand it later as the project grows.

Q: What exactly does claude init generate?
A: It creates or updates CLAUDE.md—a markdown file with project instructions. It may also create a .claude/ directory for additional configuration, depending on the version.

Q: Is CLAUDE.md the same as README.md?
A: No. README.md is for human readers, while CLAUDE.md is specifically for Claude Code to understand how to work in your project. They can overlap but serve different purposes.

Q: How do I update CLAUDE.md after running init?
A: Just edit the file directly with any text editor. There’s no special command needed—it’s a plain text file.

Q: Can I have multiple CLAUDE.md files?
A: Yes, you can place them in subdirectories to give context for specific parts of your project. Claude Code picks up the most relevant one based on the current working directory.

Related

Method: the standard formula for this calculation, rounded as each result states. See how the calculators work or report an error.

More cards in this drawer

The whole Numbers and Powers drawer →