Claude Code setup you do once and use forever
Most people install Claude Code, ask it to build something, and never touch the configuration again. That works. It also leaves a lot on the table.
This post is the first of three reference posts built from Gui Ferreira’s NDC Oslo 2026 talk, “What Claude Code Can Do That You Haven’t Tried.” Gui grouped about 40 tips into four buckets. I’m covering three of them. This one is the one-time setup: CLAUDE.md, personal instruction files, permissions, themes, and the status line.
I checked every command against the Claude Code docs as of November 2026. Where the talk and the docs disagree, I went with the docs and said so. Claude Code ships fast, so run /help in your own version if something here doesn’t match.
Coming from Cursor or Codex
Gui mentions a /import command that pulls your MCP servers, config files, and subagents from another tool into Claude Code. I couldn’t find it. It isn’t in the official commands reference, and the only /import I found documented belongs to Codex CLI, which imports from Claude Code, the opposite direction.
So for now, migrating into Claude Code is manual. The good news is that the formats are close. MCP server config in Cursor’s .cursor/mcp.json is nearly the same JSON shape as Claude Code’s .mcp.json. Skills written as SKILL.md folders follow the same format across tools, and only the directory changes. If you have an AGENTS.md, Claude Code reads it when there’s no CLAUDE.md in the working directory or above it.
Keep CLAUDE.md lean
CLAUDE.md loads into every session. Every line in it costs tokens on every task, whether the task needs it or not.
Gui cites the ETH Zurich study, “Evaluating AGENTS.md: Are Repository-Level Context Files Helpful for Coding Agents?” His summary was that long context files drop performance about 3% and raise cost about 20%. The actual findings are more specific, and the difference matters:
- LLM-generated files, the kind
/initproduces, reduced task success in 5 of 8 settings and raised inference cost by 20 to 23%. - Human-written files improved success by about 4% on average, but still added about 19% to cost.
- When researchers stripped all other docs from the repos, the generated files started helping. They were mostly repeating what the agent could already find.
So the file to delete is the one full of things the agent can discover on its own. It costs money on every task and adds nothing. A short, hand-written file of things the agent can’t find is still worth having. I wrote more about this in my CLAUDE.md instructions and memory guide.
Gui runs three questions against every instruction in his CLAUDE.md. They take a few minutes for a typical file.
- Do I need this for every task? If not, move it. A once-in-a-while procedure like running performance tests belongs in a skill.
- Is this a rule for one language or file type? Put it in
.claude/rules/. Rule files there can be scoped to paths, so your C# rules don’t load when you’re editing JavaScript. - Could the agent figure this out alone? Folder structure, where controllers live, which framework you use. The agent finds these by reading the code, and a written description drifts out of date the moment someone moves a folder.
Use imports instead of copying
If your README and your CLAUDE.md both explain the same thing, they’ll eventually disagree, and the agent will try one version, fail, and try the other. Import the file instead of duplicating it.
# CLAUDE.md
Team conventions: @docs/team-rules.md
API schema: @docs/api/schema.jsonThe @path/to/file syntax works for any file type and pulls the file in alongside CLAUDE.md.
Let /doctor do the cleanup
/doctor used to be an installation checker. Since v2.1.206 it also trims your CLAUDE.md. It cuts content Claude could derive from the codebase, like directory layouts, dependency lists, and architecture overviews. It keeps gotchas, reasoning, and conventions that differ from tool defaults. It also dedupes local CLAUDE.md files against committed ones and moves always-loaded guidance into skills or nested files that load on demand.
It reports findings first and asks before changing anything. It also flags unused skills, MCP servers, and plugins against their context cost, and slow hooks. The alias is /checkup.
From the terminal, claude doctor runs only the read-only install diagnostics without starting a session.
Three places for instructions
Most people only know the project CLAUDE.md. There are three files worth knowing, and putting things in the right one keeps your team’s file clean.
| File | Who it applies to | Commit it? |
|---|---|---|
./CLAUDE.md or ./.claude/CLAUDE.md | Everyone on the project | Yes |
./CLAUDE.local.md | Just you, this project | No, add it to .gitignore |
~/.claude/CLAUDE.md | Just you, every project | It’s in your home folder |
Gui’s example for the local file is test-driven development. He likes Claude to work test-first, but he doesn’t want to force that on his team. That goes in CLAUDE.local.md. Within a directory, Claude Code appends CLAUDE.local.md after CLAUDE.md.
His example for the user-level file is language. He’s Portuguese, so if he wanted Claude to answer in Portuguese everywhere, he’d put that in ~/.claude/CLAUDE.md once instead of copying it into every repo. There’s also ~/.claude/rules/ for personal rules that apply across all projects.
Run /memory to see every memory file Claude Code knows about for the current session, across user and project scopes.
Deny access to secrets
This is the one Gui asked the audience to promise they’d do, and I agree with him.
When Claude is chasing a hard bug, like a database connection that fails once in a while, it will read whatever it thinks might help. Config files, environment variables, .env. Nobody on your team puts production keys in those files, until the day someone does. When that happens, the keys go to Anthropic’s API as part of the conversation.
Add deny rules to .claude/settings.json:
{
"permissions": {
"deny": [
"Read(./.env)",
"Read(./.env.*)",
"Read(./secrets/**)"
]
}
}You can also manage these interactively with /permissions, which shows allow, ask, and deny rules by scope. I’d use it to confirm the rule syntax for your version, because it has changed over time.
One caveat Gui didn’t mention. A deny rule on Read blocks Claude’s file-reading tools. Check whether it also stops a shell command like cat .env in your setup. If it doesn’t, add matching Bash deny rules or turn on sandbox mode with /sandbox.
Settings live in three places, same idea as the instruction files:
| File | Scope |
|---|---|
~/.claude/settings.json | You, all projects |
.claude/settings.json | Project, shared with the team |
.claude/settings.local.json | Project, just you |
Put secret-deny rules in the shared project file so they protect everyone.
Pick a theme
/theme changes the color theme. It includes an auto option that follows your terminal’s light or dark mode, colorblind-friendly themes, and ANSI themes that use your terminal’s own palette. You can make your own by picking New custom theme… in the menu. Custom themes live in ~/.claude/themes/.
In a terminal you’re dealing with two themes, the terminal’s and Claude Code’s. This one only controls Claude Code’s.
Build a status line
If you do one thing from this post besides the deny rules, do this one. Gui treats the status line as a dashboard for the session. Once you switch models mid-session or run three sessions at once, you need one.
What’s worth showing:
- Project and git branch, so you know where you are when you have several sessions open
- Current model and effort level, which matters once you start switching models mid-session
- Percentage of the context window used
- Session cost
Run /statusline and describe what you want in plain English. Claude Code writes the script and wires it up. Run it without arguments and it builds one from your shell prompt.
Quick reference
| Command or file | What it does |
|---|---|
@path/to/file in CLAUDE.md | Imports another file instead of duplicating it |
.claude/rules/*.md | Rules scoped to paths or file types |
/doctor | Diagnoses setup and trims CLAUDE.md, v2.1.206+. Alias /checkup |
CLAUDE.local.md | Personal project instructions, gitignored |
~/.claude/CLAUDE.md | Personal instructions for every project |
/memory | Lists and edits memory files, toggles auto memory |
permissions.deny | Blocks reads or commands Claude must never run |
/permissions | Manages allow, ask, and deny rules |
/theme | Changes the color theme |
/statusline | Builds a custom status line |
The next post covers the daily workflow commands, the larger section of the talk: plan editing, rewind, side questions, context management, remote control, and running sessions in parallel.
Source
This post is based on Gui Ferreira’s talk at NDC Oslo 2026. The tips and anecdotes are his. The verification against the docs and any opinions are mine. Watch the full talk here: What Claude Code Can Do That You Haven’t Tried, Gui Ferreira, NDC Oslo 2026.
