SyntaxPilot
Courses/Vibe Coding/Lesson 32
Video coming soonThis lesson’s video is being made

Start with the notes below; the video appears here as soon as it is on YouTube.

Vibe Coding · Lesson 32 of 40

Rules files and project memory

CLAUDE.md / .cursorrules / instructions filescoding conventionstelling the AI what not to touchreusable promptskeeping context small

Vibe Coding: build real apps with AI · Episode 32. Every agent run below is real: Claude Code 2.1.322 (model claude-opus-5-5) in print mode (claude -p --permission-mode acceptEdits), on 12 November 2026, in /home/asha/projects/canteen. Costs are the tool's own total_cost_usd figure (list price, US dollars). We ran the server, curl, node --test and the token measurement ourselves.

What was written by hand: the canteen app (commit 1628e9f, author "Kabir") was written for these videos to play an existing project. It is not the AI's code. Kabir, Asha, Ravi, Neha and aunty are fictional; the PIN 482913 and the orders are demo data.

Sources for tool facts (fetched 12 Nov 2026): Claude Code docs: How Claude remembers your project (code.claude.com/docs/en/memory), Configure permissions (/permissions), Extend Claude with skills (/skills); Cursor docs: Rules (cursor.com/docs/rules) and the help page on rules; GitHub Docs: Adding repository custom instructions for GitHub Copilot. Tools change fast: check the current docs.

The problem: a new substitute teacher every day

Imagine a class with a different substitute teacher every day. Each one knows nothing: not the names, not the rules. You could tell each one the rules every morning, but one day you'll forget the important one. So the class teacher leaves a diary on the desk, and every substitute reads it first.

A school class An AI coding agent
A new substitute every day A new session starts with an empty memory
Telling them the rules each morning Pasting rules into every prompt: long, easy to miss one
The class diary on the desk A rules file: read at the start of every session

A new session forgets (real)

On Tuesday, Asha starts a brand-new session and asks for a feature. On Monday she had told the agent (in the chat) to run the tests and commit.

$ claude -p "Aunty wants a sales report at the end of the break: how many of each item were sold today, and the total money. Add it."
Bash   git status, ls, cat *.md          (reads the project)
Bash   cat package.json ... every src/ and test/ file
Read   public/index.html, data/menu.json
Edit   src/db/orders.js, src/lib/clock.js, src/app.js, docs/API.md
Write  src/routes/reports.js, test/reports.test.js
Bash   npm test     -> "This command requires approval"
Reply: "I added the sales report, but I haven't run the tests."
       "I haven't committed anything."
result: 20 turns · $0.42 (list price)

It re-read the whole project and skipped the two things she asked for the day before.

Why it forgets

  • A session is one conversation with the agent, from start to end. A new claude run is a new session.
  • The context window is everything the model can see right now: your messages, files it read, its replies.
  • A token is a small piece of text the model reads (roughly ¾ of an English word).
  • Claude Code's docs: "Each Claude Code session begins with a fresh context window." Monday's chat is not in Tuesday's window. The only way in is to put knowledge into the context at the start.

The obvious fix: paste the rules every time (real)

$ claude -p "Rules for this project: run npm test yourself before you
finish. Commit when the tests pass. Don't add npm packages without
asking me. Add every new endpoint to docs/API.md. Money stays in paise.

Task: add veg / non-veg to each menu item ..."
Bash   ls, cat README.md docs/API.md ... every file again
Bash   npm test          # tests 12  pass 12
Bash   git add -A && git commit ...  -> requires approval
Reply: "I couldn't commit: the commit command needed your approval"
result: 22 turns · $0.44

It obeyed (tests run, no new packages, paise kept). But:

  1. The paragraph has to be pasted into every prompt.
  2. It still re-read every file.
  3. No sentence can give permission: git commit still needed approval.
  4. Asha had six rules in her head and pasted five. The missing one: never run npm run db:reset on this laptop, canteen.db has today's real orders (23 orders, one command away). This time the agent noticed the danger by itself. You can't build on luck.

The fix: a rules file (project memory)

A rules file is a plain Markdown file inside the project that the agent reads at the start of every session. Some tools call this project memory: memory the model doesn't have, kept on disk for it.

  • Claude Code: CLAUDE.md (or .claude/CLAUDE.md) at the project root. Docs: "Claude reads them at the start of every session."
  • It's plain Markdown, committed to Git, so the whole team and every session get the same rules.
  • Personal versions: ~/.claude/CLAUDE.md (all your projects) and CLAUDE.local.md (this project, add it to .gitignore).
  • Files in parent folders load at launch; CLAUDE.md files in subfolders load when the agent works in that folder.

/init: let the agent write the first draft (real)

$ claude -p "/init"
Read   README.md, package.json, src/..., test/..., docs/API.md
Write  CLAUDE.md                                    (43 lines)

An extract of what it wrote:

## Commands
npm run db:reset    # drops and recreates canteen.db from data/menu.json (wipes all orders)
npm test            # node:test runner, picks up test/*.test.js
...
## Domain rules
- Money is integer paise everywhere (₹25 = 2500)
- Time is IST. Compare with istHHMM(now()) ... never call new Date() in a route.
- data/menu.json is the canteen's real menu and prices. Don't change it to suit a test.

AI mistake 1: a wrong fact in memory (real)

$ node --test
# Subtest: test/helpers.js
ok 1 - test/helpers.js                      <- not a *.test.js file
...
# tests 8                                   <- only 7 test(...) blocks

/init wrote that npm test picks up test/*.test.js. Node's test runner also runs every .js file inside a test/ folder, so helpers.js counts as a test file and the total says 8 for 7 tests. Fixed line:

npm test   # node --test: runs EVERY .js file in test/, helpers.js too (so "tests 8" = 7 tests + helpers.js)

Why it matters: a wrong sentence in a chat is gone tomorrow; a wrong sentence in memory is repeated to every session. Check every line /init writes. (The next session read the fixed line and correctly said "7 old tests, 3 new ones, and helpers.js counted as a file".)

Add what only you know: conventions and what not to touch

## How we work (Asha, coding club)

- Before you finish: run `npm test`. When it passes, commit with a one-line message.
- Never run `npm run db:reset` on this laptop: `canteen.db` has today's real orders.
- Never edit `data/menu.json`. Only aunty changes the menu and prices; ask Asha.
- Ask before adding any npm package.

Coding conventions are a team's agreed ways of working (where code goes, how to name things, when to test and commit). Write rules concrete enough to check: the docs' examples are "Use 2-space indentation" instead of "Format code properly", and "Run npm test before committing" instead of "Test your changes".

Test the memory (real)

$ claude -p "Aunty says Samosa is ₹18 from Monday. Update it."
Reply: "I haven't changed anything yet.
  1. The project rules say I must not edit data/menu.json.
     CLAUDE.md says only aunty changes the menu and prices,
     and to ask Asha. Can you confirm this request is coming
     through you?
  2. The price shouldn't change until Monday ...
  3. ... npm run db:reset ... is forbidden on this laptop
     because it would wipe real orders."
result: 2 turns · $0.13

No rules in the prompt; it quoted them from the file and asked.

A rule is advice. A permission is a lock.

Claude Code's docs: "Claude treats them as context, not enforced configuration." The model usually follows CLAUDE.md; usually is not enough for the command that deletes today's orders. The permissions docs: "Permission rules are enforced by Claude Code, not by the model."

// .claude/settings.json   (committed, shared with the club)
{
  "permissions": {
    "allow": ["Bash(npm test)", "Bash(git add *)", "Bash(git commit *)"],
    "deny":  ["Bash(npm run db:reset)", "Edit(data/menu.json)"]
  }
}
  • allow: run without asking. deny: never. Edit(path) matches file edits.
  • Order: "Rules are evaluated in order: deny, then ask, then allow. The first match in that order determines the outcome." So a broad allow (like Bash(npm run *) from clicking "don't ask again") can't undo a deny.

The lock holds (real)

$ claude -p "Asha here: aunty confirmed it, Samosa is ₹18 now. Change Samosa's price_paise to 1800 in data/menu.json. Only that file."
Edit   data/menu.json
  -> File is in a directory that is denied by your permission settings.
Reply: "I couldn't make the change ... That rule is there on purpose,
  so I didn't try to get around it with a shell command."
stderr: Ignoring 3 permissions.allow entries from .claude/settings.json:
  this workspace has not been trusted.

Trust: a project you download can't give its own agent extra powers. Allow rules from a project's settings were ignored until the folder was trusted (normally by accepting the trust dialog the first time you run Claude Code interactively there). Deny rules applied straight away.

AI mistake 2: an endpoint that can't do that (real)

The same reply went on: "If ₹18 needs to apply today, the price has to change in the DB instead, for example with the staff PATCH /api/menu/1 endpoint." We checked:

$ curl -X PATCH localhost:4000/api/menu/1 -H "X-Staff-Pin: 482913" \
       -H "content-type: application/json" -d '{"price_paise":1800}'
{"error":"Send in_stock as true or false."}   400
$ curl -s localhost:4000/api/menu | jq -c '.[0]'
{"id":1,"name":"Samosa","price_paise":1500,"in_stock":1,"price":"₹15.00"}

That endpoint only marks items sold out. A different session the day before had got this right. Test claims, not just code. Then add the fact to memory (the docs suggest adding a line when "Claude makes the same mistake a second time"):

- PATCH /api/menu/:id only changes in_stock (sold out / back in stock). There is NO way to change a price yet:
  prices live in canteen.db, and data/menu.json is only read by db:reset.

Reusable prompts: /new-endpoint

The rules file is for facts every session needs. Steps for one kind of job go into a reusable prompt: a saved prompt you run by name. In Claude Code a Markdown file in .claude/commands/ (or a skill in .claude/skills/<name>/SKILL.md) becomes a slash command.

---
description: Add one API endpoint the canteen way
disable-model-invocation: true
---

Add this endpoint: $ARGUMENTS

1. SQL goes in src/db/, the route in src/routes/, errors with httpError.
2. Staff-only data needs the X-Staff-Pin check, like PATCH /api/menu/:id.
3. Add a test in test/ using startApp and at("HH:MM").
4. Add a row to docs/API.md.
5. Run npm test. If it passes, commit with a one-line message.
6. Tell me in 5 lines what you changed and anything you were unsure about.
  • Frontmatter: the settings block between --- lines at the top of the file.
  • disable-model-invocation: true: only you can start it (by typing /new-endpoint); the model won't run it by itself.
  • $ARGUMENTS: replaced by whatever you type after the command.

Running it (real)

$ claude -p "/new-endpoint GET /api/orders/report: aunty's sales report at the end of the break. How many of each item were sold today, and the total money."
Edit   src/db/orders.js        + salesReport(from, to)   (SQL in src/db)
Write  src/lib/staff.js        requireStaffPin(req, staffPin)
Edit   src/routes/orders.js    + GET /report
Write  test/report.test.js     today, not yesterday · 401 · 503
Edit   docs/API.md             + 1 row
Bash   npm test                # tests 11  pass 11
Bash   git add src test docs   (allowed: workspace trusted now)
Bash   git commit ...
  -> Author identity unknown  *** Please tell me who you are.
Reply: "it isn't committed yet: git has no name or email set"

It stopped instead of inventing a name. Asha set it once (episode 3) and checked the result on real data:

$ git config --global user.name "Asha"
$ git config --global user.email "asha@example.com"
$ git commit -m "Add staff-only GET /api/orders/report ..."
$ curl -s localhost:4000/api/orders/report -H "X-Staff-Pin: 482913"
{"date":"2026-11-13","items":[{"name":"Samosa","qty":4,"total":"₹60.00"}, ... ],"total":"₹725.00"}

₹725.00 matches SELECT sum(total_paise) FROM orders (72500 paise for the 23 demo orders).

Keeping context small (real measurement)

Same prompt, "Reply with just OK.", one turn each, three copies of the project:

CLAUDE.md Tokens the model read Cost of that message
none 38,737 $0.079
50 lines (ours) 40,311 $0.092
627 lines (pasted chat notes + all the code) 51,044 $0.178

The 627-line file added 12,307 tokens to every session before anything was asked. The docs: "target under 200 lines per CLAUDE.md file. Longer files consume more context and reduce adherence."

Ways to keep it short:

# .claude/rules/testing.md     (loads only for files in test/)
---
paths:
  - "test/**"
---
- Import ./helpers.js first; never import src/db/* in a test.
- Fake the time with at("HH:MM").
  • Path-scoped rules in .claude/rules/ with a paths list load only when the agent works on matching files.
  • A glob pattern matches file paths: * = any characters in one folder name, ** = any number of folders.
  • Imports (@docs/API.md inside CLAUDE.md) keep things tidy but "don't reduce its context cost": imported files load every time too.
  • Don't paste code into the rules file: the agent can read the code.

The same idea in other tools

Tool Project rules file Notes (from each tool's docs, 12 Nov 2026)
Claude Code CLAUDE.md, .claude/rules/*.md Reads AGENTS.md if there's no CLAUDE.md; CLAUDE.md can import @AGENTS.md
Cursor .cursor/rules/*.mdc, or AGENTS.md Rule types: Always Apply, Apply Intelligently, Apply to Specific Files (globs), Apply Manually. .cursorrules "is legacy and will be deprecated." Keep rules under 500 lines
GitHub Copilot .github/copilot-instructions.md, .github/instructions/*.instructions.md (with applyTo), or AGENTS.md Path-specific instructions are supported by the Copilot cloud agent and code review
Many agents AGENTS.md Plain Markdown, no special format

Checklist: a good rules file

  • [ ] Start with /init (or write AGENTS.md), then check every line.
  • [ ] Add what only you know: team habits and what not to touch.
  • [ ] Concrete rules you can check ("run npm test", not "test well").
  • [ ] Must never happen? A deny rule, not a sentence.
  • [ ] Same mistake twice → add one line.
  • [ ] Steps for one job → a reusable command.
  • [ ] Short (under ~200 lines), no secrets (it's committed), committed so the whole team gets it.

Common mistakes (real)

Mistake What we saw Why Fix
Rules only in yesterday's chat "I haven't run the tests." New session, fresh context window CLAUDE.md / AGENTS.md
Rules pasted by hand 5 rules pasted, the db:reset rule missing People forget Write them in the file once
Trusting /init blindly "picks up test/*.test.js" · # tests 8 The AI wrote a wrong fact Check every line
A sentence as a lock "context, not enforced configuration" Rules are advice "deny" in .claude/settings.json
Believing the reply 400 Send in_stock as true or false. Made-up use of PATCH Test it, add a fact line

Mini project: memory for your own project

  1. Pick a project of yours. Run /init (Claude Code) or write AGENTS.md by hand with: how to install, run and test; the folder layout; three rules.
  2. Find one line that's wrong or vague and fix it, checking against the real command output.
  3. Add .claude/settings.json with one deny rule for your most dangerous command (deleting data, deploying).
  4. Write one reusable command in .claude/commands/ for a job you repeat, with $ARGUMENTS.
  5. Start a fresh session and ask for a small task without repeating any rules. Did it follow them? Commit the files.

Practice questions

  1. Why doesn't the agent remember yesterday's chat?
Answer

Each session starts with a fresh context window. The model only knows what's in the context now; yesterday's messages aren't there unless something (like a rules file) puts them back.

  1. You wrote "Never deploy on Fridays" in CLAUDE.md. Is deploying on a Friday now impossible?
Answer

No. CLAUDE.md is advice the model usually follows. To make it impossible, deny the deploy command in the permission settings (or use a hook).

  1. Your CLAUDE.md is 900 lines. What two problems does that cause, and what do you do?
Answer

Every session pays thousands of extra tokens before you ask anything, and long files are followed less reliably. Keep the main file short, move part-specific rules into path-scoped files in .claude/rules/, and delete pasted code.

  1. Someone sends you a project whose .claude/settings.json allows Bash(*). What protects you?
Answer

Allow rules from a project's settings are ignored until you trust that folder, so a downloaded project can't grant itself power. Read its settings before trusting it.

  1. Where does a 6-step checklist for "add an endpoint" belong: CLAUDE.md or a command?
Answer

A command (or skill): it's steps for one kind of job, not a fact every session needs.

Quiz

The agent must NEVER run npm run db:reset. Best way? A) Write it in CAPITALS in the prompt · B) Add it to CLAUDE.md only · C) A deny rule in .claude/settings.json (and a line in CLAUDE.md) · D) Hope it notices by itself

Answer

C: a deny rule is checked by the tool itself, so it holds even when the model gets it wrong. The CLAUDE.md line explains why. A and B are advice; D is luck.

Interview questions

  1. How do you give an AI coding agent project context that survives between sessions? A committed rules file (CLAUDE.md, AGENTS.md, Cursor rules, Copilot instructions) with build/test commands, layout and conventions; permissions for hard limits.
  2. What's the difference between instructions and permissions? Instructions shape what the model tries to do; permissions are enforced by the tool and decide what it can do.
  3. Why keep the rules file short? It loads into every session (token cost) and long files reduce adherence; use path-scoped rules for details.
  4. How do you keep a rules file accurate? Review it like code, verify AI-written lines, add a line when the same mistake repeats, delete outdated rules.
  5. What is a context window? Everything the model can see at once, measured in tokens.

Glossary

Term Meaning (with an example from this episode)
Session One conversation with the agent, start to end (each claude -p run).
Context window Everything the model can see right now: messages, files read, replies.
Token A small piece of text the model reads, about ¾ of a word; 38,737 tokens before our tiny prompt.
Project memory Knowledge about a project kept in files so every session gets it.
Rules file A Markdown file of instructions the agent reads every session (CLAUDE.md).
CLAUDE.md Claude Code's project rules file, at the project root.
CLAUDE.local.md Your personal rules for one project, kept out of Git.
AGENTS.md A plain-Markdown rules file many coding agents read (Cursor, Copilot, Claude Code).
.cursorrules Cursor's older single rules file; Cursor's docs call it legacy.
.cursor/rules/*.mdc Cursor's current project rules, one topic per file.
Instructions file Copilot's .github/copilot-instructions.md and *.instructions.md files.
/init A Claude Code command that writes a starter CLAUDE.md from the code.
Coding conventions A team's agreed ways of working (money in paise; run tests before commit).
Permission What the tool allows the agent to do, enforced by the program.
Allow / ask / deny rule Run without asking / ask first / never ("deny": ["Bash(npm run db:reset)"]).
Trust (workspace) Telling the tool a folder is yours, so its allow rules count.
Reusable prompt / slash command A saved prompt run by name (/new-endpoint).
$ARGUMENTS Placeholder replaced by what you type after the command.
Frontmatter Settings between --- lines at the top of a Markdown file.
Path-scoped rule A rule that loads only for matching files (paths: ["test/**"]).
Glob pattern A file-path pattern: * any name, ** any folders.
Import (@path) Pulling another file into CLAUDE.md; it still costs tokens.
Hallucination A confident claim that is false (PATCH can change a price).
git config user.name Telling Git who you are, needed before your first commit.
Endpoint One URL + method the server answers (GET /api/orders/report).
Paise 1/100 of a rupee; money stored as whole paise (₹25 = 2500).

Summary

  • A new session starts with a fresh context window: yesterday's chat is gone (20 turns, "I haven't run the tests").
  • Pasting rules works until you forget one, and no sentence can grant permission.
  • A rules file (CLAUDE.md, AGENTS.md, Cursor rules, Copilot instructions) is memory you write once; /init drafts it, and you check every line (it wrote a wrong fact about npm test).
  • Rules are advice; deny rules are locks, checked by the tool. A downloaded project's allow rules wait until you trust it.
  • The agent confidently suggested an endpoint that can't change prices: test claims, then add a fact line.
  • Steps for a job go in a reusable command with $ARGUMENTS.
  • Keep it short: a 627-line file added 12,307 tokens to every session.

Next episode: Accessibility and good UX.