Make your project AI-friendly

An AI agent is only as good as what it can read about your project. A handful of plain text files — and a folder you can explain in one breath — turn every future session from "let me figure out what this is" into "I already know; let's build." No code required.

↳ The thinking behind it, in Academy: AI-native craft — the seven best-practices.

The idea, in one line

You're not writing for a computer. You're leaving notes for the next person who opens the project — and these days that person is often an AI agent. A project that explains itself is a project an agent can move through quickly, and break rarely. Like a well-kept workshop: tools where you'd expect them, a note on the wall about what's half-finished.

The files that do the work

All of them are .md files — Markdown, just text with light formatting (a # Heading, a - list). You can open and edit them in any text editor. Four pull most of the weight:

File	What it is
`README.md`	The front door. What this project is, who it's for, how to run it. The first thing a human or an agent reads.
`CLAUDE.md`	The brain of the project — the agent's standing brief. What it should always know before touching anything.
`changelog.md`	A short running log of what changed and when. The project's memory.
`wishlist.md`	What you'd like next, in plain words. Ideas the agent can pick up when you say "do the next thing."

README.md — the front door

Keep it short. Someone (or some agent) landing here cold should understand the project in under a minute. A good shape:

# Project name

One sentence on what this is and who it's for.

## What's here
- web/   — the public website
- scripts/ — small helper tools

## How to run it
brew install ...
npm run dev

## Where it lives
Pushed to GitHub; Cloudflare rebuilds on every push.

Why it matters: the README answers the questions an agent would otherwise have to guess at — and a guess is where things quietly go wrong.

CLAUDE.md — the brain of the project

This is the standing brief the agent reads first, every session. Not a tutorial — the house rules. Things that are true now and would be expensive to re-discover: where things are, what to never touch, how you like changes made.

# CLAUDE.md — what to know before you touch this project

## What this is
A static marketing site + a few automation scripts.

## Ground rules
- Source of truth is git. A push to GitHub deploys it — so push deliberately.
- Never commit secrets, API keys, or personal data. Use placeholders.
- Edit existing files over creating new ones where you can.

## Layout
- web/ is the site. scripts/ is tooling. Don't mix them.

## When unsure
Ask before doing anything destructive (deletes, renames, force-push).

Why it matters: the agent loses its memory between sessions. CLAUDE.md is how it remembers your project — the difference between an agent that respects your setup and one that learns it the hard way.

changelog.md + wishlist.md — memory and direction

Two tiny files that punch above their weight. The changelog is the past: a dated line for each meaningful change, newest on top. The wishlist is the future: a loose list of what you'd like, no ceremony.

# changelog.md
## 2026-06-27
- Added contact form to the homepage.
- Fixed the broken link in the footer.

## 2026-06-20
- First version live.

# wishlist.md
- A blog section.
- Dark-mode toggle.
- Newsletter sign-up.

Why it matters: together they let you say "what did we change last week?" or "do the next thing on the wishlist" and have the agent know exactly what you mean. Use UTC dates (2026-06-27) so the log reads the same wherever anyone is.

A folder you can explain in one breath

You don't need a clever structure — you need an obvious one. Group by what things are:

my-project/
  README.md        # front door
  CLAUDE.md        # the brain
  changelog.md     # what changed
  wishlist.md      # what's next
  web/             # the website
  scripts/         # small helper tools
  n8n/             # automation workflows (if any)

Folder	Holds
`web/`	The website — pages, styles, images.
`scripts/`	Small standalone tools — a backup script, a data tidy-up.
`n8n/`	Automation workflows, kept apart from the site.

The rule of thumb: if you can point at a folder and say what's in it in three words, an agent can too.

Why this makes every session faster and safer

Faster — the agent reads the README and CLAUDE.md and starts working, instead of spending your first ten minutes re-learning the project.
Safer — the ground rules ("never commit secrets", "ask before deleting") are written down once and honoured every time, not left to chance.
Yours — these are plain files in your git repo. No vendor, no lock-in. They travel with the project and outlive any one tool. That's the maker's way: own your workshop.

Put it into practice — Academy: AI-native craft → · Source of truth for it all: Git & GitHub