DEV Community

rene
rene

Posted on

One repo, five rules files: how to keep .clinerules, .cursorrules and AGENTS.md from drifting apart

#ai #webdev #productivity #tutorial

If you use more than one AI coding tool, your repo probably has this problem: the same instructions copy-pasted into .clinerules, .cursorrules, AGENTS.md, CLAUDE.md and .github/copilot-instructions.md. A month later they disagree, and each tool behaves differently on the same codebase.

A developer on Hacker News described exactly this recently: switching harnesses when one hits its usage limit, and maintaining 20+ config files just to keep a project portable. Here is a low-tech way to keep it under control without any new tooling.

1. Pick one source of truth

Write the rules once in AGENTS.md (plain markdown). Everything else is generated or a pointer.

2. Keep rules short and testable

Rules that work across tools are concrete:

  • "Run pytest -q before declaring a task done."
  • "Never edit files under migrations/ that are already committed."
  • "Do not add a dependency without saying why in the PR description."

Vague rules ("write clean code") get ignored by every tool.

3. Sync with a 15-line script 

from pathlib import Path

src = Path("AGENTS.md").read_text(encoding="utf-8")
for target in [".clinerules", ".cursorrules", "CLAUDE.md"]:
    Path(target).write_text(
        "<!-- generated from AGENTS.md, do not edit -->\n" + src,
        encoding="utf-8",
    )
    print("wrote", target)
Enter fullscreen mode Exit fullscreen mode

Run it in a pre-commit hook so drift is impossible.

4. Split by repo type

A Python API, a Next.js app and a CLI need different rules (test command, lint command, forbidden directories). Start from a template per repo type instead of one giant generic file.

I put together six repo-type templates (each as .clinerules and .cursorrules, plus a short guide) as a pay-what-you-want pack, minimum $1: https://renevibe76.gumroad.com/l/toahua

The sync script above is free and works with any rules you write yourself.

What tool combination are you juggling, and which rules file do you trust most?

Top comments (0)