Most people treat CLAUDE.md like a prompt file.
That’s the mistake.
If you want Claude Code to feel like a senior engineer living inside your repo, your project needs structure.
Claude needs 4 things at all times:
• the why → what the system does
• the map → where things live
• the rules → what’s allowed / not allowed
• the workflows → how work gets done
I call this:
The Anatomy of a Claude Code Project 👇
━━━━━━━━━━━━━━━
1️⃣ CLAUDE.md = Repo Memory (keep it short)
This is the north star file.
Not a knowledge dump. Just:
• Purpose (WHY)
• Repo map (WHAT)
• Rules + commands (HOW)
If it gets too long, the model starts missing important context.
━━━━━━━━━━━━━━━
2️⃣ .claude/skills/ = Reusable Expert Modes
Stop rewriting instructions.
Turn common workflows into skills:
• code review checklist
• refactor playbook
• release procedure
• debugging flow
Result:
Consistency across sessions and teammates.
━━━━━━━━━━━━━━━
3️⃣ .claude/hooks/ = Guardrails
Models forget.
Hooks don’t.
Use them for things that must be deterministic:
• run formatter after edits
• run tests on core changes
• block unsafe directories (auth, billing, migrations)
━━━━━━━━━━━━━━━
4️⃣ docs/ = Progressive Context
Don’t bloat prompts.
Claude just needs to know where truth lives:
• architecture overview
• ADRs (engineering decisions)
• operational runbooks
━━━━━━━━━━━━━━━
5️⃣ Local CLAUDE.md for risky modules
Put small files near sharp edges:
src/auth/CLAUDE.md
src/persistence/CLAUDE.md
infra/CLAUDE.md
Now Claude sees the gotchas exactly when it works there.
━━━━━━━━━━━━━━━
Prompting is temporary.
Structure is permanent.
When your repo is organized this way, Claude stops behaving like a chatbot…
…and starts acting like a project-native engineer.
Most RAG pipelines are: chunk → embed → ANN search.
@PageIndexAI explores a different design: vectorless indexing for reasoning-centric retrieval over documents (page-aware context, deterministic lookup surfaces, and explicit citation grounding).
Great direction for controllable/traceable LLM systems.
- vectorless document index
- reasoning-based retrieval flow
- page-level evidence targeting
But it still may not be a great choice for coverage tasks that mainly focus on sparse retrieval, like BM25, what do you think?
Repo: https://t.co/i9ioUOEAWL
While everyone is trying to integrate more .md context files into their repo, this study shows why we should avoid them or keep them minimal.
The best practice is to mainly include failure workflow clues rather than rich, repetitive context.
Here is the great video explaining by @theo
https://t.co/4WMzgCVoE0
Software development is undergoing a renaissance in front of our eyes.
If you haven't used the tools recently, you likely are underestimating what you're missing. Since December, there's been a step function improvement in what tools like Codex can do. Some great engineers at OpenAI yesterday told me that their job has fundamentally changed since December. Prior to then, they could use Codex for unit tests; now it writes essentially all the code and does a great deal of their operations and debugging. Not everyone has yet made that leap, but it's usually because of factors besides the capability of the model.
Every company faces the same opportunity now, and navigating it well — just like with cloud computing or the Internet — requires careful thought. This post shares how OpenAI is currently approaching retooling our teams towards agentic software development. We're still learning and iterating, but here's how we're thinking about it right now:
As a first step, by March 31st, we're aiming that:
(1) For any technical task, the tool of first resort for humans is interacting with an agent rather than using an editor or terminal.
(2) The default way humans utilize agents is explicitly evaluated as safe, but also productive enough that most workflows do not need additional permissions.
In order to get there, here's what we recommended to the team a few weeks ago:
1. Take the time to try out the tools. The tools do sell themselves — many people have had amazing experiences with 5.2 in Codex, after having churned from codex web a few months ago. But many people are also so busy they haven't had a chance to try Codex yet or got stuck thinking "is there any way it could do X" rather than just trying.
- Designate an "agents captain" for your team — the primary person responsible for thinking about how agents can be brought into the teams' workflow.
- Share experiences or questions in a few designated internal channels
- Take a day for a company-wide Codex hackathon
2. Create skills and AGENTS[.md].
- Create and maintain an AGENTS[.md] for any project you work on; update the AGENTS[.md] whenever the agent does something wrong or struggles with a task.
- Write skills for anything that you get Codex to do, and commit it to the skills directory in a shared repository
3. Inventory and make accessible any internal tools.
- Maintain a list of tools that your team relies on, and make sure someone takes point on making it agent-accessible (such as via a CLI or MCP server).
4. Structure codebases to be agent-first. With the models changing so fast, this is still somewhat untrodden ground, and will require some exploration.
- Write tests which are quick to run, and create high-quality interfaces between components.
5. Say no to slop. Managing AI generated code at scale is an emerging problem, and will require new processes and conventions to keep code quality high
- Ensure that some human is accountable for any code that gets merged. As a code reviewer, maintain at least the same bar as you would for human-written code, and make sure the author understands what they're submitting.
6. Work on basic infra. There's a lot of room for everyone to build basic infrastructure, which can be guided by internal user feedback. The core tools are getting a lot better and more usable, but there's a lot of infrastructure that currently go around the tools, such as observability, tracking not just the committed code but the agent trajectories that led to them, and central management of the tools that agents are able to use.
Overall, adopting tools like Codex is not just a technical but also a deep cultural change, with a lot of downstream implications to figure out. We encourage every manager to drive this with their team, and to think through other action items — for example, per item 5 above, what else can prevent a lot of "functionally-correct but poorly-maintainable code" from creeping into codebases.
@WSJ Kurdish people in Rojava are facing massacre by the Syrian ISIS-backed government while the world is watching.
Kurds are being sold out by the left/right again.
#KobaneUnderAttack#Rojava