Search for a command to run...
Hands-on technology leader with 10+ years building scalable, mission-critical systems at Goldman Sachs, Brevan Howard and fast-growing fintechs. Expert in cloud-native architectures, distributed data pipelines and high-throughput systems; experienced in migrating legacy platforms and designing AI-enabled services. Proven track record delivering reliable platforms that process millions of transactions daily.
No comments yet. Be the first to comment.
It’s an Exoskeleton, and That Changes Everything Most people are thinking about AI the wrong way. They imagine it as a coworker:Something you assign tasks to… wait for… and hope it delivers. Sounds re
I didn’t wake up one day and decide, “AI will change everything.”My journey into AI was slower, messier, and honestly… a bit reluctant at first. If you’re a builder, engineer, or curious technologist,
Imagine a programming language designed not just for humans but also for AI.Not adapted for AI. Not retrofitted. Built from scratch so AI can read and write it easily. That’s exactly what NanoLang is. It’s a tiny, experimental language created by vet...
Most PostgreSQL optimization guides feel like laundry lists of settings and indexes. But real performance gains often come from clever ideas, not just the usual tricks. Let’s unpack a few of those ideas in ways that actually make sense for you. These...
Remember when we defeated pop-up ads? Yeah, they're back. And this time, nobody's fighting them. The Good Old Days (Of Terrible Ads) Back around 2000, the internet was a warzone. Visit any website and BAM!!! random windows would explode onto your scr...
If you are using Claude Code or any AI agent inside your codebase, the CLAUDE.md file can change everything. A good one feels like giving Claude a proper first day at work. A messy one feels like hiring someone and letting them figure things out alone.
This post will show you what to put inside your CLAUDE.md, what to avoid, and how to write it in a way that Claude can understand and follow easily.
Large language models do not automatically know your repo. Every new session is basically an empty mind.
The CLAUDE.md file is where you introduce the AI to your project: what it is, how it works, how to build it, and where important things live.
Think of it like a short onboarding note for a new colleague.
Keep things simple and direct. If someone could read it in a couple of minutes and feel ready to contribute, you are on the right track.
A useful CLAUDE.md should cover:
What the project is
Why it exists and what problem it solves
How to work with it (install, run, test, deploy)
How the folders and main parts of the repo are structured
This is not documentation for users. It is guidance for a developer stepping into the codebase for the first time.
Claude does not read everything just because it is there. It tries to use what feels relevant. If you add too much detail, you increase the chance that important parts get lost inside the noise.
Keep it light. Trim anything that is not essential for understanding the project. A shorter file is easier for humans and AI to absorb. Many good CLAUDE.md files are far under 300 lines. Some teams keep theirs closer to one page and still get great results.
If your project is large, do not try to squeeze every piece of knowledge into one file. Create small, focused documents that Claude can read only when needed.
Example folder:
agent_docs/
build.md
tests.md
architecture.md
migrations.md
Then inside CLAUDE.md you can simply say:
If you need more detail, check the agent_docs files above.
This approach keeps the main file clean and gives Claude the option to pull more context when required.
Code style rules, formatting choices and long lists of do this, don't do that make CLAUDE.md heavy and unhelpful.
Let your linters, CI and formatters handle style. Claude is better used for reasoning, planning and writing code, not nitpicking style.
If you want Claude to fix formatting, just show it the linter output directly. That is faster and more reliable.
Yes, you could ask an AI to generate your CLAUDE.md for you. But since this file shapes how the agent interacts with your code forever, spending time to write it well is worth it.
A clear, human written document will reduce confusion later and help your workflow scale. You do not need it to be perfect on day one. You just need it to be useful and kept up to date.
A strong CLAUDE.md:
is short, friendly and easy to skim
explains the project goal and structure in simple language
describes how to run, build and test the app
contains links to deeper files instead of dumping everything inside
is updated occasionally rather than forgotten
CLAUDE.md is not just documentation. It is how you teach an AI to think inside your codebase. If you treat it like onboarding instead of a rulebook, you will get faster and more reliable help from Claude every time you open a session.
If you want, tell me about your tech stack and what your app does. I can help you draft a clean CLAUDE.md that fits your project perfectly.