Claude Code

2025-12-23 → 2026-08-08

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

General usage guidelines#

Guides & workflows#

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.

Matt Pocock’s Claude Code’s system tools are SO BLOATED is a short companion to this warning about unnecessary tooling.

The same minimalism applies to the code itself: ponytail is a cross-agent skill system that makes the agent reuse existing code before writing new code (“the best code is the code you never wrote”).

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.

Stephen Turner’s open-source skill for pre-submission peer review is a research example of the same principle. The skill searches peer-reviewed literature through Consensus, records every query and result count, reports failed or capped searches, and separates concerns that threaten a paper’s conclusions from those that do not. It uses Claude Code to make a mock review auditable before submission rather than to automate an editor’s decision.

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. 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.

At the same time, avoid documenting too much. There should be a single source of truth, and that’s usually the code. If something is obvious from simply reading the files, it probably doesn’t have to be written down.

You can use HTML for human-facing documentation. It’s easier to read than markdown files, and easy to incorporate images, interactive elements, etc.

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:

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.

Skills#

See Skills

How I use it#

See How I Use It for Claude Code specifics and How I Use Them for my harness-agnostic setup.

Tips#

See Claude Code/Tips

Cognitive thrashing#

The “thinking” delays of the model push you toward multitasking — opening email, another terminal, another CC session — while CC is grinding. This easily turns into cognitive thrashing: the human becomes a scheduler with too small a working set, and the overhead of context-switching dominates real work. Running fewer parallel sessions and writing things down (so the brain doesn’t have to page them) are the practical fixes.

Alternatives#

Other terminal coding agent harnesses:

Multiplexers and interfaces for running several agents at once:

Higher-level orchestration around coding agents:

Receive my updates

YY's Random Walks — Science, academia, and occasional rabbit holes.

YY's Bike Shed — Sustainable mobility, urbanism, and the details that matter.

or RSS/Atom, Bluesky, and other options.

×