How to Customize a Code Template with Claude Code or Cursor (AGENTS.md Explained)

AI coding tools have made customizing someone else's code fast enough that buying a template and adapting it now beats building from scratch for most known app patterns. But the results vary wildly. The same request can produce a clean two-line edit or a sprawling rewrite of files that never needed touching.

The difference is almost always context. An AI tool that knows where the configuration lives, which conventions the codebase follows, and how to verify a change will edit the right file the first time. One that has to guess will guess. This guide covers how to give it that context, and the workflow that keeps every change safe to undo.

What AGENTS.md is

AGENTS.md is a plain Markdown file at the root of a project that gives AI coding agents the context a new developer would need: how the code is organized, which conventions to follow, and which commands build and test it. Think of it as a README written for agents instead of people.

It is an open format, now stewarded by the Agentic AI Foundation under the Linux Foundation, and used by more than 60,000 open-source projects. Support is broad as of October 2026:

The Claude Code detail matters. According to Anthropic's documentation, Claude Code reads AGENTS.md only when there is no CLAUDE.md or CLAUDE.local.md in your working directory or above it. If a project has both, Claude Code reads the CLAUDE.md files only, unless the CLAUDE.md imports AGENTS.md with an @AGENTS.md line. If you add your own CLAUDE.md to a template, add that import so you do not silently lose the template's instructions.

What a good AGENTS.md contains

Here is an excerpt from the AGENTS.md that ships with Merkado's appointment booking template:

## Where things live
- lib/booking-config.ts: the active config (re-exports a preset from
  lib/configs/). The form, availability, reminders, and admin all read
  from it. Switch presets by changing the one import here.
- lib/reminders.ts: reminder offsets and copy (default 24h + 1h before).
- lib/slots.ts: pure slot generator (do not call DB here; it takes data in).

## Conventions
- Public writes go through lib/supabase/admin.ts (service role) on the
  server only. Never query the DB from a client component.
- All times are stored UTC and shown in bookingConfig.timezone.

It is short, and every line does work. A file map, so the agent edits the right file. Rules that are easy to break and expensive when broken, like keeping database credentials out of the browser. And the commands to run, so the agent can check itself. A long AGENTS.md is not a better one: the tool reads it at the start of every session, and concise instructions are followed more consistently.

The workflow, step by step

1. Get it running before you change anything. Install dependencies, fill in the environment variables, and start the app exactly as the setup guide describes. If something fails at this stage, it is a setup problem, not something your AI tool broke, and it is far easier to fix before there are changes in the way.

2. Commit the clean copy. If the template did not arrive as a git repository, make it one (git init, then commit everything). This is your known-good checkpoint, and it is what makes every later step safe.

3. Open the project in your AI tool and confirm it has the context. Open the project's root folder, not a subfolder, so the tool finds AGENTS.md. Then ask it to summarize where things live and which rules it must follow. If the summary matches the file, you are ready. If it does not, point it at AGENTS.md explicitly.

4. Ask for one specific change at a time. Name the outcome you want and, where you know it, the file. Vague, compound requests produce large changes you cannot review.

5. Verify every change. Run the template's checks, usually npm run typecheck and npm test, then click through the part of the app you changed. AI-generated code is usually right, but "usually" is why the tests exist.

6. Commit after each change that passes. Small commits mean that when a change goes wrong, you undo one step instead of untangling five. If something breaks and you cannot see why, roll back to the last commit and ask again with a narrower request.

A worked example: adapting a booking app

Say you bought the appointment booking template for a barbershop. It ships with three presets (salon, consult call, home services), and the salon preset is closest. Three prompts take it most of the way.

Prompt 1, hours and timezone:

Read AGENTS.md first. In lib/configs/salon.ts, change the hours to
Tue-Sat 10:00-18:00, closed Sunday and Monday, and the timezone to
America/Chicago. Keep weeklyHours at exactly 7 entries (index 0 is
Sunday; closed days are null). Change nothing else. Then run
npm run typecheck and npm test.

Prompt 2, reminder timing:

In lib/reminders.ts, change the 24h reminder to fire 48 hours before
the appointment. Keep its id unchanged and keep the 1h reminder as it
is. offsetMinutes must stay negative. Run npm test afterwards.

Why keep the id? The app records which reminders each booking has already received by id. Rename it on a live app and bookings that already got their reminder could get it again. That is exactly the kind of detail an agent can miss, and the kind a good prompt, or a good AGENTS.md, spells out.

Prompt 3, brand voice:

Rewrite the confirmation and reminder copy in a relaxed, friendly
voice for a barbershop called Northside Barbers. Keep every token
([Name], [Brand], [When], [Service], [ManageLink]) intact, and keep
the SMS versions short.

Each prompt names the file, states the constraint the agent could otherwise break, and ends with a check. You do not have to write these from scratch: every Merkado Original ships with a CUSTOMIZE_WITH_AI.md file of tested, copy-paste prompts like these, ten of them for the booking template, from changing hours to taking a deposit with Stripe.

Where AI edits go wrong, and how to prevent it

• Secrets in the chat. Never paste API keys into a prompt. Put them in your local environment file (.env.local in most Next.js templates) and confirm that file is in .gitignore before your first commit.
• Database credentials reaching the browser. Most Supabase templates use a powerful service role key that must only ever run on the server. If a change touches data access, ask the agent to confirm that nothing new imports server-only code into a client component.
• Schema changes. A database change should be a new migration file, never an edit to one that has already been applied. Test it against a local database before it touches production.
• Big-bang requests. "Rebuild the admin dashboard" in one prompt produces a diff nobody can review. Break it into steps you could describe to a human contractor.
• Integrations that fail quietly. Many templates skip a channel, such as SMS, when its key is missing, so a broken integration can look like a working app. After any change to notifications or payments, test the real flow with real keys in a test account.

What makes a template easy for AI to customize

If you are choosing between templates, these are the features that predict how well AI tools will handle one:

1. An AGENTS.md at the root with a file map, conventions, and commands.
2. Configuration in one place. One file the agent edits beats settings scattered across components.
3. Logic separated from side effects. Pure functions, like a slot calculator that takes data in rather than querying the database, are easy to change and easy to test.
4. Tests and a typecheck command, so the agent can verify its own work instead of you finding the bug in production.
5. TypeScript. Types catch a whole class of AI mistakes before the app ever runs.
6. Ready-made prompts for the common customizations.
7. A license that permits AI tools. Some licenses do not mention AI at all. Merkado's expressly permits it; see our guide to template licenses.

Every Merkado Original is built to this list. Whichever template you choose, the workflow above holds: context first, one change at a time, verify, commit.