davit.cc Writing

I don't have a CLAUDE.md file

2026-11-02T12:00:00+04:00

This website's code has no CLAUDE.md file. It has an AGENTS.md, and Claude Code reads that instead.

A CLAUDE.md file is a plain Markdown file that Claude Code reads at the start of every session. It's where you tell Claude what it can't work out from the code: how you ship, what you've already rejected, what never to touch.

AGENTS.md is the same idea under the name other coding tools use: "a README for agents". Codex, Cursor, Copilot and Gemini CLI read it. Since version 2.1.277, Claude Code reads it too, so one file covers all of them.

Here's what's in this post:

What Claude does with AGENTS.md.
What my AGENTS.md says.
What stays out.
How it stays right.

1. What Claude does with AGENTS.md

When a Claude Code session starts, Claude looks for a CLAUDE.md or CLAUDE.local.md in the folder you opened and the folders above it. If there isn't one, it loads every AGENTS.md it finds there instead, and you see a line like this:

no CLAUDE.md found; AGENTS.md loaded: /home/you/repo/AGENTS.md

A few more things from Anthropic's docs that are worth knowing:

An AGENTS.md inside a subfolder loads when Claude opens a file in that folder.
Your own ~/.claude/CLAUDE.md still loads next to it, so your personal rules don't go away.
If the repo has a CLAUDE.md or a CLAUDE.local.md, Claude reads that and skips AGENTS.md, unless you change Project instructions in /config to read both.
Older Claude Code versions don't read AGENTS.md on their own. On those, a CLAUDE.md with the single line @AGENTS.md pulls it in.

That last trick is what I used to have. My CLAUDE.md was that one line. Claude reads AGENTS.md by itself now, so I deleted it.

It checks the door for a note first. Then it reads the notebook.

2. What my AGENTS.md says

It has seven short sections, in this order:

Section	What it tells Claude
Ship it	Every push to `main` goes live. Show me a preview first
Stack	Plain HTML, CSS and JS, and what each file is for
Agents	The Markdown pages, API and discovery files the site serves to AI agents
Run it locally	One command, and the screen widths to check
Design rules	Colours, type, the hero, the logo, and what I already said no to
Content rules	Facts that must match my CV, and how blog posts get built
Code style	Match the code around you. Short comments, plain commit messages

The first section matters most, because it's the one Claude can't guess from the code:

## Ship it

- Every push to `main` deploys davit.cc within about a minute.
- Work directly on `main`. Davit is the only person on this repo:
  no pull requests, no feature branches.
- Because a push is a deploy, show Davit a preview of any visual change
  and push once he's happy. Copy fixes and small bug fixes can go straight in.

That second rule exists because I typed this into a thread once:

since i am only one working on this no need to create prs just push to main

I said it once. It's been in the file since.

The design rules work the same way. Each one is a decision I already made, written down so I don't make it again:

- Light only. Mostly cool grey with a faint lavender glow.
  Davit found stronger lilac "too colourful". Never use green accents.
- Project cards: the same dust in each product's own soft colour.
  Illustrated scenes and redrawn product UIs were tried and rejected.

"Tried and rejected" saves the most time. Without that line, a new session has no way to know I already turned those ideas down.

The content rules are short facts with no room for guessing: "15+ years of experience", the section is called "Projects", not "Work", and "Experience must match Davit's CV".

3. What stays out

Anything the code already says. Claude can see the framework, the folders and the function names. Repeating them just makes the file longer.

Long how-tos. Writing a blog post here takes a style guide, image rules and a build script. That lives in a skill in .claude/skills/, which Claude loads only when it writes a post. My AGENTS.md gives it one line: follow the write-blog-post skill.

Rules that must never break. These files are advice, and Claude can miss advice. If something must never happen, the docs point you to a hook that blocks it instead.

Secrets. The file is in git. Mine names the AUTH_SECRET setting but never its value.

Anthropic suggests keeping each file under 200 lines, because longer files get followed less. Mine is about 80.

It took the one page that mattered.

4. How it stays right

Instructions go stale like any other doc. My first project instructions for this site still said it deployed from the master branch through GitHub Pages, after I had moved it to main and Cloudflare.

Now the rule is simple. When a convention changes, AGENTS.md changes in the same commit. And when I correct a choice, like "too colourful", it becomes a line in the file.

So the file keeps growing, one line per "no", and I rewrite lines when they stop being true.

Questions people ask

Do I still need a CLAUDE.md file?

Only in a few cases: you want rules that only Claude should read, or you're on a Claude Code version older than 2.1.277. Otherwise an AGENTS.md is enough. If you do keep both, put @AGENTS.md at the top of the CLAUDE.md, because Claude reads the CLAUDE.md and skips the other one.

Should AGENTS.md be in git?

Yes, so everyone on the project, people and agents, gets the same rules. Personal rules go in ~/.claude/CLAUDE.md, which stays on your machine. Skip CLAUDE.local.md here: having one makes Claude stop reading AGENTS.md.

Is it the same as Claude Projects instructions?

No. AGENTS.md lives in the code and travels with it. Project instructions live in Claude Projects and cover how you work: where the repo is, who approves what. I keep both short. They overlap only on how to ship, because that rule matters everywhere.

Start yours

Run /init in Claude Code. It reads the codebase and writes a first CLAUDE.md.
Rename it to AGENTS.md, so every agent reads it.
Delete everything Claude could find by reading the code.
Add how you ship and what you've already said no to.
Each time you correct Claude, add one line.

Write down the "no". Skip the rest.

More on how this site gets built in my agentic coding workflow, or see what I've worked on in my CV.

My agentic coding workflow

2026-10-23T12:00:00+04:00

I rebuilt this website in two days and didn't write a line of code.

Claude wrote it. I said yes or no. Mostly no.

That's my agentic coding workflow, and it comes down to three things:

One project per product.
Rules I write down once.
Short answers.

1. One project per product

Every product I work on gets its own Claude Project: this site, Rillow, Bundle and Unposed.

I tell the project what I want. It starts a separate thread for each task, and each thread works on its own copy of the code. Three things can be in progress while I'm doing something else.

When I come back, I check what's done and what's waiting on me. It works from my phone too.

Boris Cherny, who made Claude Code, used to juggle ten or more sessions by hand (VentureBeat). A project does the juggling for me. More on that in how I use Claude Projects.

2. Rules I write down once

Every project starts with one paragraph of instructions. Mine says where the code lives, that I'm the only one working on it, and that every push goes live, so show me a preview first.

The code has its own rulebook too, an AGENTS.md file. A few real lines from it:

- Light only. Mostly cool grey with a faint lavender glow. Davit found stronger lilac "too colourful". Never use green accents.
- Keep pixel art pixel-exact: nearest-neighbour scaling only.

Almost every rule in there is a "no" I said once.

When I correct Claude, I tell it to remember. Then I never say it again.

Every "no" ends up on the board.

Mitchell Hashimoto calls this engineering the harness: every mistake becomes a rule, so it doesn't happen twice.

I write the rules Claude builds I look at a preview Yes: it ships
No: it tries again and remembers why

3. Short answers

Here's what I actually typed during the redesign:

"too colourful"
"i love it"
"childish"
"not real"
"Pixel is better"
"mario in threejs"

That last one became Shiba Land, a small platformer. With a Shiba instead of Mario, because I'd like to keep this website.

None of this is code review. It's taste, and taste is most of my job now.

Simon Willison says writing code is cheap now. When three versions of a page take a few minutes, picking one is the work.

Three versions. Pick one.

If a choice changes what I'm building, Claude asks on a card with a few options and a recommendation. I pick one and go back to what I was doing.

By the numbers

The redesign
Time	About two days
Pull requests	1
Files changed	43
Lines of code I wrote	0
Replies in the thread	165

What I keep for myself

I decide what gets built. I approve anything that can't be undone. On this site every push goes live, so I see a preview first.

The part I keep.

And I read anything with my name on it. Including this post, which has been rewritten three times. The first version sounded like a robot. The second had too many details. The third was fine, and then I found a style I liked better.

What still goes wrong

Instructions go stale. My first setup said the site deploys from the master branch. It doesn't. The first thread read the code and fixed it. Trust the code over your own summary.

Drawing from scratch. The first hand-coded Shiba came out "silly". The 3D one was too red. Claude does much better with clear rules, like pixel art, or with a design I've already made.

Long threads get heavy. After a while every new message costs more. New work gets a new thread.

Try it

Pick one side project and make it a project.

Write one paragraph of instructions: where the code is, how to check a change, what needs your OK.
Put the rules for the code in AGENTS.md.
Ask for a preview before anything ships.
When you correct it, tell it to remember.

Then mostly say no.

If you're hiring someone who works like this, here's my CV.

How to use Claude Projects the right way

2026-10-23T12:00:00+04:00

I run this whole website from one Claude Project. The redesign, the favicon, the little games, these posts. All of it.

If you want to know how to use Claude Projects well, here's the short version: brief it once, keep feeding it work, and answer when it asks.

The rest of this post is the long version, from my own setup.

What a project is now

Anthropic redesigned Projects in September 2026.

Before, a project was a folder: some files, some instructions, some chats.

Now it's a chat with a coordinator. You tell it what you want. It answers, or it starts a thread. Each thread is a full Claude Code session with its own copy of your code. Threads share a memory and report back when they're done.

You only talk to the one in the middle.

It's in beta on Pro and Max, on the web, desktop and mobile apps (docs). Most guides online still describe the old folder version.

1. Let Claude set it up

I didn't write my setup. My first message was:

Help me set up this new project from my recent work. Look through my recent sessions and repositories, identify the main thread of work, and propose a project setup: a short name, the repositories it should include, an environment, concise project instructions drawn from what kept coming up, and one or two optional routines. Show me the proposal before changing anything.

It came back with a name, instructions and a weekly check of the live site. I said "yes".

2. Keep the instructions short

Instructions are the brief every thread reads first. Mine are one paragraph:

Site is davit.cc, built from the main branch of davit-khaburdzania.github.io and served by a Cloudflare Worker (wrangler.jsonc). Davit is the only one working on the site, so don't open pull requests: commit and push straight to main. Every push to main deploys davit.cc automatically within about a minute (Cloudflare's GitHub connection), so a push is a production change: show Davit a preview of visual changes before pushing. Keep profile details (location "Tbilisi, Georgia", website davit.cc) consistent across the site, GitHub and LinkedIn. Verify changes on the live site after each push.

The first version got the branch wrong. The first thread read the code and fixed it.

The rest got added as I went. "No pull requests" came on day two, when I told it I'm the only one working on the site.

3. Know where things go

A project keeps context in three places:

Where	What goes in it	Example from my site
Instructions	Rules every thread needs	"Show a preview before pushing"
Memory	Decisions you make along the way	"Unposed goes last in the Projects list"
`AGENTS.md` in the repo	How the code is built	"Never use green accents"

Memory fills itself when you say "remember". If you only write one of these, write the repo file. Every session reads it, project or not.

Memory. Fills up faster than you'd think.

4. Send work, then walk away

Talk to the coordinator like a colleague. Questions get answered. Work becomes a thread.

When a thread needs a decision, it asks with a few options and a recommendation. When my CV needed updating, it asked whether it should edit the PDF or I'd do it myself. I picked "I'll do it".

One thing isn't obvious: if a thread needs your approval, answer in that thread. Saying "go ahead" to the coordinator doesn't reach it.

5. Use your own computer when you have to

Some of my work needs my Mac. Paper, the design app I use, only runs there.

So that one thread runs on my machine through Remote Control, and everything else stays in the cloud. Turn it on in the desktop app under Settings > Claude Code, then pick "Work locally" in the project chat.

6. Watch your usage

Every thread is a full session and several run at once, so a project uses your plan faster than a chat.

Two habits help:

New work, new thread. Long threads get expensive. My redesign thread hit 165 replies before I let it go.
Close what you're done with. A thread that watches a pull request wakes up every time CI fails.

You can also switch to cheaper models in the project settings.

Frequently asked questions

When should I use a project instead of a chat?

When the work keeps going, like a product or a site you keep improving. A quick question is fine in a chat.

What's the difference between Claude Projects and Claude Code?

Projects are built on Claude Code. Every thread is a Claude Code session. The project adds the coordinator, shared instructions and memory.

Can I share a Claude Project with my team?

Not yet. During the beta a project belongs to one person.

Do cloud threads get my local skills and MCP servers?

No. They get the connectors and skills from your claude.ai account and whatever is in your repo. Anything installed only on your laptop needs a thread running on your computer.

The short version, again

Brief it once. Let it remember the rest.

Here's how I work day to day, and here's my CV.

Languages and frameworks don't matter anymore

2026-10-23T12:00:00+04:00

I've shipped Rails, Elixir, Node, TypeScript, Python and React professionally. For 15 years, picking the stack was the first big decision on every project.

It isn't anymore.

If you're asking what the best language for AI coding is, my answer is anything where the agent can check its own work fast. The syntax barely matters.

What changed

Agents write most of the code now, in whatever language you give them.

This year I've worked on a Next.js app for Rillow, an iPhone app, an Android app and a Chrome extension for Bundle, and this site in plain HTML. Each time the platform picked the language. Claude handled all of them.

Andrej Karpathy says agents now write almost all of his code (Yahoo Tech). Simon Willison puts it simply: writing code is cheap now.

When code is cheap, the language you write it in is a detail.

But languages aren't equal

To be fair, there's evidence they differ:

Elixir scored highest on one benchmark, as its creator José Valim points out.
TypeScript catches the most common mistake. In one study, almost all compile errors in AI-written code were type errors (GitHub).
Go gets praise from Armin Ronacher for being easy for agents to read and test (A Language for Agents).

Look at why each one wins, though. It's the same reason every time: the agent finds out fast when it's wrong.

That comes from the tooling. The syntax has little to do with it.

All it needs is a light that comes on when it's wrong.

What still matters

Fast feedback. Tests that run in seconds and a strict type checker beat any language switch.
One way to do things. Conventions help agents for the same reason they help new hires.
The platform. An iPhone app goes through Xcode and App Review whatever you write it in.
Code you can read. You still review it. You still own it.

So what should you pick?

A new web app: TypeScript, with strict checks on.

Your team already knows Rails or Elixir: keep it and write good tests.

Performance-critical, native, or brand new with little public code: this is where the choice still deserves real thought.

Everything else: pick what fits the platform and move on.

Close enough.

What this means for hiring

Years in one framework tell you less than they used to. The agent already knows the framework.

I'd look for someone who splits work into small pieces, checks the results properly and knows what not to build.

The short version

The best language for AI coding is the one that tells the agent it's wrong. Everything else is preference.

Here's how I work with agents day to day, and here's my CV.