appwrite/rules: The Generator That Turns Appwrite Best Practices Into AI Instructions

A deep dive into the AGENTS.md tool that teaches copilots how to build Appwrite apps the way Appwrite wants them built.

8 min read • View on GitHub • More from appwrite

A wide editorial scene of a developer desk where scattered notes about SDK docs, best practices, and security rules are being pulled into one clean markdown sheet that feeds a mechanical assistant arm. The image explains the repo’s thesis: Appwrite is converting human guidance into a single instruction surface for AI coding tools. — The project treats instructions like infrastructure. One generated file becomes the place where Appwrite’s opinions land.

Key Takeaways

appwrite/rules is less a docs project than a rules compiler that turns Appwrite’s architecture preferences into AI-readable instructions.
Its real opinion is that copilots should not improvise direct SDK usage when a centralized, team-aware pattern is safer and easier to scale.
The generator’s modular assembly model matters because it lets common policy, language-specific guidance, and framework-specific setup land in one file without turning into prompt soup.
Appwrite is signaling that the next developer experience layer is machine-readable policy, not just human-facing documentation.

The new layer between docs and code

The most interesting thing about appwrite/rules is not that it generates AGENTS.md. It is that it treats AI guidance as part of the product surface. Instead of hoping a copilot will infer Appwrite’s conventions from scattered docs, the repo packages those conventions into instructions the model can actually follow.

That shifts the job of developer experience. Traditional docs explain the API to humans. This tool aims at the agent that writes the code, and that changes what good guidance looks like. It has to be specific, opinionated, and structured enough to survive a prompt window.

The repo is a rules compiler, not a content folder

At a glance, this could look like a pile of templates. It is closer to a compiler. The central orchestrator, src/lib/rules-generator.js, assembles a final markdown file from modular pieces: shared implementation patterns, language-specific rules, framework-specific setup, and fallback behavior for vanilla targets.

A single file is assembled from modular rule sources. The point is not just reuse. It is consistency across languages and frameworks.

// Conceptual flow, simplified
async function generateRules({ language, framework, target }) {
  const common = await getCommonPatterns();
  const langRules = await getLanguageRules(language);
  const frameworkRules = await getFrameworkRules(language, framework) ?? getVanillaRules(language);

  const sections = await Promise.all([
    common.auth,
    common.database,
    common.storage,
    common.functions,
    langRules.examples,
    frameworkRules.init,
  ]);

  return assembleMarkdown({ target, sections });
}

That structure matters because it keeps the generator scalable. If Appwrite adds a new framework or language, it can extend the output without rewriting the whole system. The content stays modular, but the output still reads like one coherent policy document.

The real product is the opinion

The sharpest part of the repo lives in src/lib/languages/common/implementation-patterns.js. This is where Appwrite stops being neutral. The generator does not just say how to use Appwrite. It tells the AI what architecture patterns should be preferred, what access patterns are authoritative, and what kinds of shortcuts should be avoided.

A close-up of a precision machine where labeled rule cards for auth, database, storage, and functions slide into a central compiler box. The box emits a single markdown file with strict callouts about team roles, ownership, and avoiding direct SDK calls from UI code. The image explains how opinionated fragments become one enforceable instruction set. — The core mechanism is not a prompt dump. It is a narrow funnel that turns many rule fragments into one opinionated output.

That is a meaningful product decision. A generic prompt file says, in effect, “here is some context.” This repo says, “here is the approved way to build.” It turns guidance into a guardrail, which is a much stronger claim.

The team-first bias is especially revealing. By pushing role and ownership patterns into the generated instructions, the repo is encoding a backend philosophy. Appwrite is not only describing its primitives. It is shaping how those primitives should be composed in production systems.

Why sectional assembly beats one giant prompt

The generator’s Promise-based composition model is a practical answer to a real problem. One giant instruction file is hard to maintain, hard to localize, and easy to dilute. Sectional assembly lets the repo fetch common rules in parallel, layer language-specific examples on top, and keep framework setup precise without making the whole thing brittle.

const sections = await Promise.all([
  getAuthRules(),
  getDatabaseRules(),
  getStorageRules(),
  getFunctionRules(),
]);

return [header, ...sections, footer].join('\n\n');

The upside is more than code cleanliness. It means the generated output can stay dense and opinionated without becoming unreadable. The AI gets a single artifact, but the maintainers get a system they can actually extend.

A BaaS wrapper for the AI era

Compared with traditional SDK docs, appwrite/rules is trying to sit one layer higher. Docs teach humans how to call an API. This tool teaches copilots what architecture to prefer when they generate code around that API. That is a bigger ambition than reference material.

Approach	Who it serves	How opinionated	Scales across stacks	Enforces architecture
Generic AI prompt files	Humans and assistants	Low	Poorly	No
Traditional SDK documentation	Humans	Medium	Moderately	Rarely
appwrite/rules generated output	AI assistants first	High	Well	Yes

That comparison is the point. If your product is a backend platform, the battle is no longer only about APIs and auth flows. It is also about the instruction layer that tells AI how to assemble those flows correctly.

What this says about Appwrite

This repo suggests Appwrite sees a new control point in developer tooling. The company is not just publishing primitives and hoping the rest of the stack behaves. It is trying to define the rules that AI assistants use when they turn those primitives into applications.

That is a strong bet. If machine-readable guidance becomes a standard part of the workflow, then the winners will not just ship SDKs and docs. They will ship the policy layer that keeps AI from wandering off script.