Vibe coding with Claude Code course Β· Module 2: A Next.js project with Claude Code
Project memory: AGENTS.md, CLAUDE.md and /init
In this lesson11
Ahoy! The map lies in SPEC.md. Before the crew sets off to build, you will hang the ship's regulations in the cabin: a file of rules that Claude Code reads at the start of every session, also a month from now.
The problem: every session starts from zero
After /clear, or tomorrow morning in a new session, Claude does not remember the conversation. It does not know that you turned Cache Components off on purpose in lesson 1_2, that after every change you want to see the result of npm run build, and that you keep the development server in a separate terminal. You explain it again or, worse, you forget. Then Claude may do something sensible from its own point of view, for example turn on Cache Components, because the wizard offers them in the recommended settings. It sees the code, but it does not see your decision.
For this there is project memory: files with instructions that Claude Code loads at the start of every conversation. You write them in plain text and keep them in the repository together with the code.
What you already have: AGENTS.md
The wizard from lesson 1_2 left an AGENTS.md file in the project, with instructions for coding agents. Open it in Cursor. All of its content sits between two markers:
<!-- BEGIN:nextjs-agent-rules -->
## This is NOT the Next.js you know
(a warning and a hint where to look for the documentation)
<!-- END:nextjs-agent-rules --><!-- and --> open and close a comment that you do not see when the file is rendered, and these two markers mean a fragment that belongs to Next.js. Inside is a warning that this version of Next.js may differ from what the model learned earlier, and an order to read the guide from the node_modules/next/dist/docs/ folder before writing code. The Next.js documentation explains that this folder holds documentation matched to the installed version, and next dev recreates the block and changes only the text between the markers, leaving the rest of the file alone.
Claude Code reads AGENTS.md as project instructions when the working folder and the folders above it hold no CLAUDE.md or CLAUDE.local.md file. At the start of a session you will then see a line similar to this one:
no CLAUDE.md found; AGENTS.md loaded: .../krakens-call/AGENTS.mdThat is proof that the Next.js warning reaches every conversation. There is also a trap: once a CLAUDE.md appears in the project, Claude stops reading AGENTS.md on its own.
Import: one line with @
The solution is an import. A line with @ and a path in the CLAUDE.md file loads the indicated file together with it, and an imported file may import further ones, at most four levels deep. Here one line is enough:
@AGENTS.mdPut it at the very top of CLAUDE.md. Claude will then read the imported file first and your rules after it, and nothing has to be copied. AGENTS.md itself does not change, so Next.js can keep refreshing its block.
/init: the first draft
The /init command generates a starter CLAUDE.md: Claude analyses the project and saves the build and test commands and the conventions it found. When a CLAUDE.md already exists, /init does not overwrite it but proposes improvements. Type in the session in the krakens-call folder:
/initClaude will ask for consent to save CLAUDE.md. Claude Code best practices say outright that from here the work consists mostly of deleting lines. Read the file in Cursor and mark in your mind everything that Claude would find in the repository by itself: the list of folders, a description of the App Router, the package versions from package.json.
The request: keep what the code does not show
You will shorten the draft with one request. Say in it what is to stay, what is to go and what Claude will not find in any file:
Request for Claude Code:
Shorten @CLAUDE.md to three parts: check commands, traps and
decisions. At the very top add the import line @AGENTS.md. Remove the
description of folders and architecture, because you will read them
from the repository. Write in plain sentences, no capital letters for
emphasis. To the traps add that Cache Components are off on purpose,
and to the decisions that I start the npm run dev server myself in a
separate terminal.The request says what stays, what goes and why. The last two pieces of information are knowledge that is not in the code: the absence of a cacheComponents line in next.config.ts does not say that it is a decision and not an oversight.
What Claude wrote: a short CLAUDE.md
Open CLAUDE.md in Cursor. Yours will have different words but a similar shape. At the top stand the import and the commands:
@AGENTS.md
# Check commands
- Types: npx tsc --noEmit
- Lint: npm run lint
- Build: npm run build, after every step of the planThese are just commands, without sentences like "always check types". The documentation explains that Claude needs a command to check its own work along the way. This part enforces nothing: it supplies tools, and you still ask for proof in the request.
Below the commands stand the traps and the decisions, that is, knowledge that Claude will not read out of the project files:
# Traps
- Cache Components are off on purpose (there is no cacheComponents in next.config.ts). Do not turn them on.
- Tailwind 4: configuration lives in app/globals.css, there is no tailwind.config.js file.
- Fix type errors at the source, without any and @ts-ignore.
# Decisions
- I start the npm run dev server myself in a separate terminal, you do not start it.
- The plan for the home page is in the SPEC.md file.Every line is something that is not visible in the code, or something you already corrected in this location: the Tailwind 3 syntax from lesson 1_3 and the silencing of types from lesson 1_4. SPEC.md stands here without @, so it is a mention and not an import: the plan is not loaded into every conversation, and Claude will open it when it is needed.
What not to put in
Claude Code best practices list things that today only get in the way:
- a description of the architecture and the file layout: Claude reads the repository itself;
- CAPITAL LETTERS and the word IMPORTANT: current models follow a plain sentence, and too much emphasis makes them apply the rule excessively; if a line gets lost, the file is too long;
- everything "just in case": every line takes a little of Claude's attention on every task, needed or not.
The memory documentation also recommends a length: under 200 lines per file. The captain's advice: no passwords or keys, because CLAUDE.md goes to the repository together with the code.
Notes only for you
Notes you do not want in the repository, for example "explain every Git command to me before running it", write in a CLAUDE.local.md file in the main project folder. Claude reads it right after CLAUDE.md. The file must not reach Git, and the .gitignore from the wizard does not know it, so ask Claude to add one line to .gitignore:
CLAUDE.local.mdFrom now on Git skips your notes, and in Source Control you will not see that file. Note: CLAUDE.local.md also switches off the independent reading of AGENTS.md, but in our project the import at the top of CLAUDE.md takes care of that.
Two tools at the end. When you say "remember that...", Claude will save it in auto memory, that is, in its own notes on your computer, outside the project. For something to land in CLAUDE.md, say it outright: "add this to CLAUDE.md". The /memory command shows the list of memory files, opens the chosen one in an editor and turns auto memory on or off.
The test: a new session
Memory is tested in a conversation that has not heard the previous one. Leave the session with the /exit command and start claude anew, because memory files load at the start of a session. Then ask:
Which commands will you use to check this project after a change, and
what must you not change in next.config.ts?A good answer names the three commands from CLAUDE.md and Cache Components. If Claude guesses, run /context all and check the list of Memory files: CLAUDE.md must be on it. A missing file on the list means that Claude does not see it.
Captain's review
Before you commit, check in Source Control:
- Import: the first line of
CLAUDE.mdis@AGENTS.md. - Length: a dozen or so lines, far from 200.
- The code test: at every line you ask whether Claude would find it in the repository; if so, the line goes.
- Secrets and ballast: the diff has no keys and no
CLAUDE.local.md, and.gitignorehas a new line.
A typical agent mistake in this task: while shortening, it leaves a description of the folders "for order" or adds rules in capital letters. You will catch it in the diff before you approve the change.
Next step
Ask for a commit of CLAUDE.md and .gitignore with a message like "CLAUDE.md: check commands and traps of the project". The file will grow slowly: the documentation advises adding a line when Claude makes the same mistake for the second time. In the next lesson you will build the landing page according to the plan, and in the editor below you will look at a sample CLAUDE.md, CLAUDE.local.md and an excerpt of .gitignore.
Remember: CLAUDE.md is the ship's regulations that every new crew reads before setting sail.
Code for this lesson: CLAUDE.md
@AGENTS.md
# Check commands
- Types: npx tsc --noEmit
- Lint: npm run lint
- Build: npm run build, after every step of the plan
# Traps
- Cache Components are off on purpose (there is no cacheComponents in next.config.ts). Do not turn them on.
- Tailwind 4: configuration lives in app/globals.css, there is no tailwind.config.js file.
- Fix type errors at the source, without any and @ts-ignore.
# Decisions
- I start the npm run dev server myself in a separate terminal, you do not start it.
- The plan for the home page is in the SPEC.md file.
Spotted a mistake in this lesson?
Check yourself
Answer the questions from this lesson. Pick an answer to see right away whether it is correct.
1. The project has the AGENTS.md from the wizard, and there is no CLAUDE.md or CLAUDE.local.md. What will Claude Code load at the start of a session?
2. What is most worth putting in the CLAUDE.md of the Kraken's Call project?
3. Where will you save your own instructions for the project that you do not want sent to the repository?
Hands-on tasks in the game
- Vertical ordering
Arrange the steps of setting up project memory in Kraken's Call: