Two files sit at the front door of every project: CLAUDE.md, which onboards the model, and README.md, which onboards the human. Both fail the same way, by trying to say too much. Here is how I think about each.

Writing a good CLAUDE.md

Think of CLAUDE.md as the onboarding note you'd hand a competent contractor on their first morning, not as a rulebook. The model starts every session with no memory of your project, so the file should answer three things: what this project is and why it exists, how the code is organized, and how to build, test, and verify a change. That's it. Tech stack, directory layout, the commands that actually matter, and any tooling quirk that would otherwise trip someone up, like "use bun, not node." If you can state it in one line, do.

The hard part is knowing what to leave out. Claude reads this file with an explicit note saying the content may or may not be relevant, so anything that doesn't apply to the task at hand nudges the model toward ignoring the file entirely. That means a bloated CLAUDE.md is worse than a short one: you don't get partial compliance, you get the whole thing tuned out. Aim for under 300 lines, and be pleased if you land under 60. Every line should be true and useful in most sessions, not just the one you happened to be working on when you wrote it.

Two specific things not to put in there. First, code style rules. Formatting is a linter's job, and a linter is deterministic in a way a language model is not, so wire up a formatter and a hook instead of writing "always use single quotes" and hoping. Second, auto-generated content. Running /init gives you a draft, not a finished file. This is the single highest-leverage piece of context you control, so read every line and cut most of them.

When you do need depth, use pointers instead of prose. Keep detailed guides in something like agent_docs/running_tests.md or agent_docs/deployment.md, and let CLAUDE.md be a short table of contents with a one-line description of each, so Claude can pull in the one it needs and skip the rest. Same idea for code: reference src/auth/session.ts:42 rather than pasting a snippet that will be stale in a month. And in a monorepo, a small CLAUDE.md inside a package beats a large one at the root, because it only loads when someone is actually working there.

Writing a good README

Your first paragraph has one job: tell a stranger what this is and what problem it solves, in plain sentences, above the fold. Not a logo, not a badge wall, not an animated banner. Someone landed here from a search result or a dependency list and is deciding within about ten seconds whether to keep reading. If the top of your file is an <a> tag wrapped around an image, you have spent that budget on decoration. Say what it does, say who it's for, and if there's a comparable tool, say how you differ from it. Then answer the next two questions in order: can I run this (requirements, install command), and what does using it look like (one short, real, copy-pasteable example). A well-known example is nanostores, which opens with an intro and immediately shows telling code. That ordering, what it is, then how to install, then how to use, then everything else, covers most of what readers actually came for.

Write it so it reads fine as plain text. A README gets opened in a terminal, in a text editor, in a diff, and by a screen reader, not only in GitHub's rendered view. That means minimal raw HTML, no layout tricks, and headings and lists doing the structural work. Screenshots genuinely help for anything with a UI, since they let people evaluate the project without installing it, so include them, but always with prose that stands on its own when the image doesn't load. The rule someone put well: this is a README, not a SHOWME. Product marketing belongs on the product website. And never embed tracking pixels, which I'd treat as an outright breach of trust rather than a style question.

Cut anything the platform already gives you or that will rot. Contributor lists, star counts, and license widgets are already rendered by GitHub, so duplicating them just adds lines to maintain. Emoji-per-heading reads as spam to a lot of people, and a wall of CI badges tends to communicate less than one sentence saying the test suite runs on push. Long API references, architecture deep-dives, and contribution workflows belong in linked files like docs/ or CONTRIBUTING.md, with the README pointing at them. The front door should stay a front door.

Two things that get skipped and shouldn't. First, name your tech stack and your actual requirements, including versions, because "does this fit my environment" is a question people ask before anything else. Second, verify your install and usage commands on a clean machine, or at least a fresh container, before you ship them. A broken first command is the single most common way a README fails, and it costs you the reader immediately. State the license plainly somewhere near the bottom, keep the whole thing short enough that scrolling isn't a chore, and revisit it whenever the setup steps change. If you want a scaffold to start from, makeareadme.com is a reasonable template.

The common thread

Both files reward restraint. The CLAUDE.md that gets followed and the README that gets read are the ones that said less. Write the version that stays true across most sessions and most readers, point at the rest, and stop.