AI Coding Rules: 12 Files That End the Guesswork

An assistant that invents a method name costs a review cycle. It writes Auth::login() where the engine has login_with_secret(), the reviewer catches it, and the next suggestion repeats the mistake. Written ai coding rules remove that loop, because the model reads the real signature before it types.

Code: Atomic-Framework-Skills, GPL-3.0 licensed.

Twelve files cover one framework area each, and together they describe a PHP 8.1 framework with 25 component folders and 44 documentation files.

What an ai coding rules file replaces

It replaces the guess that a model makes when a repository is too large to fit in a prompt. Without a file, the model sees a few open tabs and general knowledge of PHP, and general knowledge is where the invented method comes from.

With a file, the assistant gets the class names, the bootstrap chain, the route conventions and the names of the helpers that exist. The distance between a suggestion and working code shrinks to the distance between the file and the engine source, which the authors check by hand.

Twelve areas instead of one document

The split follows the framework: overview, core, application and auth, data, CLI and API, events and hooks and i18n and mail, mutex and session, queue and scheduler and telemetry, theme, plugins, tools and WebSockets, and a doc map.

One file per area is a decision about context, not about tidiness. A prompt that loads a single 300-line file about sessions gives better answers than one that loads everything and hopes the model finds the relevant paragraph.

The overview file exists to be read first, and the doc map exists for the moment when an agent needs to find a document rather than an API.

Why the rules have to come from the source

The repository states the rule in its contributing guide: do not add methods or helpers that do not exist in the source. A skill with one invented function is worse than no skill, because the assistant trusts it and so does the reviewer.

The same guide asks for a ## Guardrails note whenever a mistake is easy to repeat. That is the part most rule sets skip: a note about what the model gets wrong here, written after it got it wrong, is worth a paragraph of general advice.

How the files load

In VS Code the path goes into github.copilot.chat.skills.instructionFilesGlob pointing at skills/**/*.md. The agent does not read them all: it picks by the description in the frontmatter, or you call one by name.

That behaviour is worth understanding before buying into it. A vague description means the wrong file loads, and a wrong file produces confident answers about the wrong subsystem.

What it does not do

It does not write the feature, does not run tests and does not know the client’s domain. It also does not stay current by itself: the files are audited against the engine by hand, and a framework release that changes a signature makes a skill stale until someone updates it.

What to check in someone else’s rule set

Ask where the signatures came from, and open one at random against the source. If the file cannot be traced to a line of code, it is prose about a framework rather than a reference to it.

Then check the descriptions. A rule set whose files all sound alike will load the wrong one, and the failure looks like a bad model rather than a bad library.

What it changes in the estimate

A day of writing and auditing the rules, saved on every ticket that touches an unfamiliar subsystem. The measurable part is review time: fewer cycles spent on a method that never existed, and fewer conversations about why the assistant is confident and wrong.

Related: php framework for business apps for the framework these rules describe, and php project skeleton for the repository a team starts from.