Managing & Amending AI Rules

TL;DR: How to change AGENTS.md’s Project conventions section over time, including order, format, sourcing, and how to check a change actually works.

AGENTS.md (see Setting Up AI Rules) isn’t a file you write once and forget. It changes as the codebase changes and as the team’s own rules change. This page explains how to update it properly, so a change actually works (it really changes what the AI tool does) and stays consistent with everything else already in the file.

The one boundary that matters: what changes often, and what doesn’t

AGENTS.md has three parts, and they don’t change at the same rate:

	`learn_shopify_api` instruction + the reference-removal note, `## Building a feature from a Figma design`	`## Project conventions`
Changes when…	The AI tooling or the Figma pipeline itself changes	A theme-specific rule changes: naming, spacing, colors, accessibility, code style
How often	Rarely	Regularly, as the project grows
Who touches it	Whoever maintains the AI tooling setup	Anyone on the team amending a project rule

Every change described on this page means a change to ## Project conventions. The file’s other two parts aren’t off-limits the way an older, more rigid “don’t touch Shopify’s generated content” rule might imply, there’s no separate generated baseline left in this file to protect, see Setting Up AI Rules for why. They’re just a different kind of change: a decision about how the tooling works, not a day-to-day project rule, so don’t fold one into the other.

Section order within `## Project conventions`

The section’s real, current order, from the top:

Code style and readability. This comes first because it governs how every other rule gets applied: simple over clever, explicit over implicit, no premature optimization.
JavaScript: Web Components in separate asset files, then CSS: {% stylesheet %} and BEM. The two implementation layers, side by side.
Schema conventions (translations, presets, conditional settings), then settings into variables, then CSS custom properties on the outer element. The schema-to-markup-to-style pipeline, in the order it actually happens.
Accessibility, then Documentation. Cross-cutting requirements that apply to everything above.
Check your work after every file. A process step, placed right after the content it applies to.
Naming: the sol prefix, then Spacing settings, then Color palette, then Reuse before you create. The project’s specific conventions, grouped together.
The QA checklist and the golden rule. Final checks, last on purpose, since they’re applied after everything else has already been read and used.

The rule for adding new content: find the existing subsection it belongs under first. Only add a new ### subsection if it genuinely doesn’t fit anywhere that already exists, and place it near the other subsections it’s most related to, not at the bottom by default.

Format requirements

Plain Markdown, using ## and ### headings, matching the style already used throughout ## Project conventions.
No literal */ sequence inside any comment or fenced code block. This includes inside a glob pattern (a file-matching pattern like **/*.liquid) written in prose. For example, write “loads on .liquid files” instead of the literal glob, in case this file ever ends up read as code by some tool downstream. This isn’t a Markdown rule. It matters specifically if anything treats this file as source code.
Specific, checkable rules, not vague ones. See the comparison table in Setting Up AI Rules. A rule that doesn’t change what gets generated isn’t worth keeping in the file.
Don’t repeat generic Liquid/Shopify knowledge. That content was deliberately removed from this file in favor of the shopify-liquid skill and the learn_shopify_api / search_docs_chunks MCP tools, which stay current automatically (see Shopify’s Official AI Toolkit). A rule belongs in ## Project conventions only if it’s a decision specific to this project, not a fact true of any Shopify theme.

The update process, step by step

Decide which existing subsection of ## Project conventions it belongs under. Follow the section order above.
Check it isn’t actually a generic Liquid/Shopify fact rather than a project decision. If it is, it belongs in the shopify-liquid skill’s territory, not here — see Shopify’s Official AI Toolkit. Link to the relevant handbook page instead, if the reader needs more context.
Base the rule on an official source. Confirm the underlying claim against shopify.dev, help.shopify.com, or Shopify’s own repos. Never write a rule based on a third-party blog, a forum answer, or “this is probably how it works.”
Write the rule so it’s specific and checkable, matching the style already used in ## Project conventions: a plain statement, a code comparison (✅/❌) if it helps clarify the rule, and a link to the relevant handbook page for more detail.
Test it against real generated output (see below).
Commit AGENTS.md. There’s nothing else to regenerate or commit alongside it. CLAUDE.md and .github/copilot-instructions.md are symlinks (files that just point to another file). They reflect the change automatically. Git tracks the symlink itself, which never changes, separately from what it points to.
Write a specific PR description. Note which rule changed and why, not just “updated AI rules.”

Testing whether a change actually works

A rule that reads correctly to a human isn’t necessarily one that changes what the model does. Before you consider a change finished, do this:

Ask your AI tool to do something the old rule (or the lack of any rule) would have gotten wrong.
Check whether the new rule actually changes the output the way you intended.
If it doesn’t, the rule probably needs to be more specific or placed more prominently in ## Project conventions, not just longer.

This is the same test described in Setting Up AI Rules, applied to one new or changed rule instead of the whole section.

Keeping a record of why a rule exists

## Project conventions should stay focused on the rules themselves, not a history of every change. But the reasoning behind a rule that isn’t obvious is worth writing down somewhere a future developer can find it.

A one-line explanation inline, when the reason isn’t obvious from the rule itself. The section already does this in places, for example explaining why the sol prefix exists, not just that it does.
The PR description, for anything that needs more context than fits in one line. You can find it later with git log or git blame on AGENTS.md, which is exactly why step 7 above asks for a specific, non-generic PR description.

What NOT to do when making changes

❌ Don’t	Why
Add a day-to-day project rule to the `learn_shopify_api` instruction or the Figma workflow section	Those two parts are about how the tooling itself works, not naming, spacing, or CSS conventions — see Setting Up AI Rules
Add a rule based on something you read in a blog post or forum answer without confirming it against `shopify.dev` or `help.shopify.com`	Breaks the sourcing rule this file is built on
Repeat generic Liquid/Shopify knowledge the `shopify-liquid` skill already covers	That content was deliberately removed from this file — a frozen copy would just go stale again
Add a vague rule (“write good code,” “be performant”)	Doesn’t change what the model produces. See Setting Up AI Rules’s vague-versus-specific comparison.
Look for a build or regeneration step	There isn’t one. `CLAUDE.md` and `.github/copilot-instructions.md` are symlinks, always up to date.

Do / Don’t

✅ Do	❌ Don’t
Add a new rule to `## Project conventions`, under whichever existing subsection it fits.	Adding an ordinary project rule change to the `learn_shopify_api` instruction or the Figma workflow section. Those change for different reasons — see the table above.
Hold yourself to the same sourcing standard while writing rules that `## Project conventions` itself asks for while following them.	Writing a rule from memory or a third-party source without confirming it against official Shopify documentation first.
Test every change against real generated output before calling it done.	Repeating generic Liquid/Shopify knowledge the `shopify-liquid` skill already covers, instead of checking first and linking out if more context is needed.
Write a specific PR description for every `AGENTS.md` change.	Assuming a clearly-written rule works without testing it against an actual generation task.

Key takeaways

## Project conventions is the one section that changes regularly. The file’s other two parts (the learn_shopify_api instruction and the Figma workflow section) change rarely, and for a different reason — see Setting Up AI Rules.
Section order within ## Project conventions: code style first, then the implementation layers (JS/CSS), then the schema-to-style pipeline, then cross-cutting requirements (accessibility, documentation), then the project’s specific conventions (naming, spacing, color, reuse), then final checks (QA checklist, golden rule) last.
Format: ## and ### headings, specific and checkable rules, no repeating generic Liquid/Shopify knowledge the shopify-liquid skill already covers.
Process: find the right existing subsection, confirm it’s a project decision and not a generic platform fact, base it on an official source, write it specifically, test against real output, commit AGENTS.md (nothing to regenerate), write a specific PR description.