Claude Code

2025-12-23 → 2026-03-08

Anthropic’s AI coding agent. The following content and documents are constantly updated.

General usage guidelines#

Guides & workflows#

Claude Code in Action — free course by Anthropic
Boris Cherny (creator of CC): how he uses CC, tips from the CC team
Pedro Sant’Anna: Claude Code setup for academic research — specialized agents, quality gates, and a “contractor mode” orchestrator

Don’t over-engineer#

The base LLMs are getting increasingly capable and generally evolve towards a direction where carefully crafted prompts, tools, and crutches become unnecessary. Because of base LLMs’ raw power and the rapid development, it may not be a good idea to spend too much time building extra infrastructure, skills, tools, etc. around CC. Soon, they may become obsolete, or worse, they can restrict CC’s power by imposing too much constraints while creating maintenance burden.

A good example is a recent study by Gloaguen et al. (2026) that evaluated whether repository context files (like AGENTS.md or CLAUDE.md) actually help coding agents. They found that context files tend to reduce task success rates while increasing inference cost by over 20%. The files encouraged agents to do more work (broader exploration, more thorough testing, more file traversal) without improving outcomes. The recommendation is that if you do write context files, describe only minimal requirements.

Focus on verification#

Although code generation is becoming so easy, verification is still not trivial. You want to think & invest more in verification. CC also works best when it can verify its own work. Write tests (or ask to write tests), check those tests, create scaffolding for verifying the work. Consider the principle of Test driven development.

Use plan mode#

Shift + Tab cycles through the three modes: normal, plan, accept-edits. At the beginning of a task, it is a good idea to use the plan mode. When prompted in the plan mode, CC asks you to clarify requirements and spend more context to have a broader understanding of the whole codebase.

Use git commit as checkpoints#

Don’t just let CC write huge amount of code without any commits. Try to regularly check & commit, each of which becomes the checkpoint that you can revert back if things go wrong. It is probably good idea to commit when all the tests pass and you are confident about the current state of the code (cf. the Test driven development loop).

Use plain text (markdown) documents#

CC has massive context window. Still, try to document, document, document. When CC behaves in an undesired manner, prevent it by writing it down in CLAUDE.md. When there is a list of todo items, create a document and use it as an intermediary medium between you and CC. Do you have high-level design principles that should be applied consistently across the project, be sure to keep it written down. Make things cumulative.

Basic settings#

The preferences and settings are stored in CLAUDE.md (at project root or in .claude/) and .claude/settings.json. CLAUDE.md is for natural language instructions such as project overview, tool preferences, directory structure, etc. and settings.json is a structured file for explicit permissions, hooks, plugins, etc. There are three types of CLAUDE.md:

~/.claude/CLAUDE.md: instructions applied to every project that can be managed with dotfiles.
CLAUDE.md: Created by /init command. Instructions for the specific project usually shared across the team.
CLAUDE.local.md: Not committed to shared repo. Instructions just for you within the project.

In CC session, you can type # and that initiate the “memory mode” where you can add instructions to one of those CLAUDE.md files.

See the Official documentation for more details.

Global preferences#

You can create global CLAUDE.md and settings.json and put it in ~/.claude/ directory, which is used by Claude to store various temporary files and settings. These settings and preferences are applied to every CC sessions unless overridden by project-specific settings.

You can incorporate these files into your dotfiles repo.

Tips#

If you’re annoyed by manually approving trivial commands, add them the pre-approved list. These can be stored in the global setting file. You can ask CC to create one.

You can also ask CC to set up certain hooks. For instance, you can ask it to run a linter/fixer (e.g., ruff) whenever a script is edited or created. CC will automatically run it.