DEV Community

Cover image for Your CLAUDE.md doesn't scale. Version your AI standards as code.
Prathak Malik
Prathak Malik

Posted on

Your CLAUDE.md doesn't scale. Version your AI standards as code.

#ai #productivity #opensource #tutorial

Every team using AI coding agents starts the same way: someone drops a CLAUDE.md (or .cursorrules, or a copilot-instructions.md) into a repo. It works. So the next repo gets one too. And the next.

Then you look up and you have 20 repos, 6 teammates, and 3 different AI tools — and no two of those config files are the same. Which one is right? Nobody knows.

I hit this wall running an integration platform with dozens of small repos. This post is the pattern I landed on, and a small open template you can clone to do the same.

Why a single instructions file breaks

A single file is perfect for one repo and one person. At team scale it fails in five predictable ways:

  1. It doesn't scale. Every repo gets a slightly different copy. There's no "the standard" — there are 20 forks of it.
  2. It drifts. Someone improves the file in one repo. That improvement never reaches the other 19.
  3. It's unversioned. No history, no ownership, no review. Your "AI brain" is the one artifact in your stack nobody code-reviews.
  4. It's tool-locked. Cursor's format isn't Claude's isn't Copilot's. Switch tools and you start over.
  5. It rots. The code changes; the instructions don't. Six months later the agent is confidently working from a map of a city that's been rebuilt.

None of these are exotic. They're just what happens when a copy-pasted file meets a growing team.

What already exists (and what it doesn't fix)

  • Curated rule lists (e.g. awesome-cursorrules) are great for inspiration, but they're copy-paste, single-tool, and have no sync or freshness.
  • Skill/agent sync tools distribute tools across agents. Useful — but they solve distribution, not your team's standards, versioning-as-review, or the rot problem.
  • The Agent Skills standard + AGENTS.md are the right substrate to build on, not competitors.

The gap: nobody treats the standards themselves as code — owned, versioned, reviewed, and automatically distributed.

The pattern: standards-as-code

Three moves:

  1. Put your standards in one git repo. Two kinds of artifact:
    • Rules — standing behavior ("always validate input", "never log PII").
    • Skills — task workflows ("here's how to cut a release"), in the portable SKILL.md format.
  2. Auto-sync them into your editor. A setup script links skills/ and rules/ into your tool's config directory. Git hooks re-run the sync on every pull / checkout / rebase.
  3. Change them through pull requests. Improving a standard is now a reviewed diff, not a silent edit in one repo. 
Git repo (source of truth)          ~/.cursor/
  skills/  ──────────────└            skills/   (junction/symlink)
  rules/   ──────────────┤  setup +   rules/    (synced .mdc)
                         └── git hooks ─────────→ every workspace, every teammate
Enter fullscreen mode Exit fullscreen mode

Because rules sync to the user level, they apply in every workspace automatically. Update the repo, everyone git pulls, and the whole team's standards move together — no per-repo copies.

Why this beats a bare CLAUDE.md

standards-as-code bare CLAUDE.md
Scales across repos Yes (one source) No (N copies)
Versioned + PR-reviewed Yes No
Auto-distributed Yes (sync + hooks) Manual
Freshness mechanism Yes (later in the series) No

It's the difference between a shared library and a code snippet everyone pastes.

Try it (v0.1)

I packaged the mechanism as an open template: agent-standards-kit (this post pins v0.1).

git clone https://github.com/prathakmalik/agent-standards-kit.git
cd agent-standards-kit
./scripts/setup.ps1     # Windows/Cursor; no admin needed
Enter fullscreen mode Exit fullscreen mode

Restart Cursor and your sample skills + rules are live. Swap in your own — the repo ships templates and a de-identified worked example.

My honest take

This is not another skills manager — that niche is crowded. It's a methodology plus a starter template, proven on a real multi-repo platform. Its value is the boring, durable stuff: team+repo scoping via plain git, review of changes, and (coming in this series) a loop that keeps the standards from rotting. If you're one dev on one repo, a single file is genuinely fine. The moment there's a team, treat your AI standards like code.

Coming up next (v0.2): One source of truth is great — but your team doesn't all use the same AI tool. Next post: making the same skills and rules work across Cursor, Claude Code, and GitHub Copilot, with cross-platform setup (bash and PowerShell). Star the repo to follow along.

If you found this useful, a ⭐ on the repo helps more than you'd think.

Top comments (0)