Skip to content

Module 01 / Lesson 02

Give Your Agent Project Memory with AGENTS.md and Scoped Rules

Module 01 · Real-World ContextStep 02 of 03

Never ask an AI to write code until you have defined what success and failure look like.

Imagine your payment or messaging service degrades during peak hours. You need your team to publish an urgent incident notice to customers. If you ask an AI coding agent with a vague prompt like "build a status page with a publish button", it quickly outputs a flashy mockup with billing tabs and animations you never requested, but clicking Publish does not actually save or update anything.

Narrated lesson · 1:50
Read the narration transcript

A new session misses an old decision

Yesterday we agreed to use the status app’s existing database client. Today I open a new agent session and ask for a change to the Publish form.

The plan adds a second client and reaches for an unsafe type assertion. The new session started from the repo it can see. Yesterday’s conversation was a poor place to store a rule the whole project relies on.

Put the right instruction in the right file

I move the database rule into AGENTS dot M D. I add where to find the existing server client and the exact command this repository uses to check its types.

Guidance for the status badge belongs nearer the interface. Keep it separate from database rules so a backend task has a smaller, more relevant set of instructions to read.

Clients differ. Claude Code uses its own project memory file and supports imports. Check your client’s docs and verify the arrangement from a fresh session.

Fix a rule the agent silently ignores

Here’s the failure. The agent is changing the incident form, but the rule uses camel case. Antigravity can discard that rule before the agent ever sees it.

Use always on with an underscore for a rule that should always apply. Use a glob, or file pattern, for a rule limited to components. If a long file still loses its ending, Antigravity documents a twenty-four-thousand-byte limit per file.

For Claude Code, I can import the shared file from Claude dot M D, or use a symlink if the team verifies its checkout workflow. I confirm the actual rule loaded from a new session.

Repeat the task in a clean session

Start a fresh session and ask where it would make the change. Does it point to the form and the existing action?

Then review the proposed files. A copy-only change should have a good reason to touch the database. If it does, ask for the rationale before approving the plan.

The everyday problem

Yesterday the agent reused src/lib/supabase/server.ts. Today, a new chat proposes a second database client and a new dependency for the same form. You can repeat the instruction every morning, or give the decision somewhere durable to live.

Project memory means guidance checked into the repository that the agent can discover at the start of a task. In this lesson we’ll make the incident publishing rule easy to find and confirm it actually reached the agent.

Why the agent got it wrong

A chat and a repository have different lifetimes. Project conventions disappear when they live only in a conversation. A long context dump can hide the important line among many irrelevant examples. Some clients have discovery and size rules that determine whether a file is even included in the first place.

Separate discovery from compliance. If an Antigravity rule has an invalid trigger, the model may never see it. If the rule appears in context and the agent still picked the wrong helper, sharpen the instruction and check its work.

The tool and technique

Put rules you expect nearly every contributor to follow in AGENTS.md. Cover the existing stack, the owner of important behavior, commands that really exist, and checks the agent should run. In this app, name the current Supabase helper and the package scripts rather than telling the agent to use best practices.

Put focused UI rules near the relevant work or use the client’s documented file patterns. A file pattern, also called a glob, matches paths such as src/components/**/*.tsx. The rule for visible focus belongs on component work. The approved database client belongs in project guidance.

Write rules a fresh session can find

Keep AGENTS.md in the repository and record the commands and constraints the agent should reuse. Add scoped rules for work that needs them, such as accessibility in UI files. When a client expects a different file, follow its documented import or symlink support and verify it on a clean checkout. Windows setups may require extra symlink permissions.

# AGENTS.md
- Use src/lib/supabase/server.ts for authenticated server calls.
- Use the existing test fixtures for publishing changes.
- Run pnpm typecheck and the affected tests before reporting results.

# CLAUDE.md may import the shared file with @AGENTS.md.
# For teams that verify symlink support on their checkouts:
ln -s AGENTS.md CLAUDE.md

# Save the following as .agents/rules/incident-form.md
---
trigger: glob
globs: "src/components/**/*.tsx"
---
Check keyboard dismissal and preserve the draft on a failed save.

Open a fresh session and ask it to name the server client and check command before editing. Antigravity ignores scoped files without valid frontmatter, uses always_on for always-loaded rules, and truncates a single rule at 24,000 bytes. Check discovery before making the rule longer.

On screen in the status app

The before example is advice in a chat that expires. In the after example, AGENTS.md points to actual paths, records pnpm typecheck and pnpm test, and gives a boundary for database edits. A separate scoped file can require visible focus and draft recovery without loading a full UI manual during a migration review.

In Antigravity’s .agents/rules/, trigger: alwaysOn is a configuration typo. Use always_on for an always-on rule, or glob plus the globs field for a scoped rule. Claude Code can import a shared AGENTS.md through CLAUDE.md. Teams can also use a symlink after checking their platform and version-control setup.

AGENTS.md

Before

Chat-only instruction: Use our existing database client and test your work.

After

# Project instructions
- Use src/lib/supabase/server.ts for authenticated incident operations.
- Keep public reads in the existing status route.
- Put schema changes in reviewed files under supabase/migrations/.
- Run pnpm typecheck and the affected tests for publishing changes.
- Report the commands run and the results before calling the change ready.

What to watch for

Antigravity documents a 24,000-byte per-file cutoff. Keep the active file short enough to read in one sitting. Move a long release procedure into a skill. Dropping an arbitrary line count into the repo is less useful than regularly removing rules the project no longer follows.

Each tool handles nested instructions and shared files differently. Check the documented convention and what this session loaded. For Windows checkouts, an import may be easier to share than a symlink that depends on local configuration.

How you know it worked

Start a fresh chat in the checkout. Ask which Supabase helper it will use and which script it will run. Have it cite the actual file and inspect package.json before making a change. The useful evidence is the path it plans to use, the command it ran, and the resulting output.

If the agent forgets the incident-form rule, check the rule filename, frontmatter, spelling, and glob in that order. Verify it on a matching file and on an unrelated file. Next you’ll use the same evidence-first habit when the agent quotes an unfamiliar API.

References