How Your .clinerules File Became the Most Detailed Document Your Team Has Ever Written

SATIRE — At 9:14 on Monday, the engineering team at the fictional municipal software contractor Rook & Piston declared its .clinerules/ directory the canonical architecture document, replacing a Confluence space last updated during the era when Kubernetes was still described as “a Docker thing, probably.” The decision followed an exhaustive review in which Cline obeyed architecture.md twice in succession, while no human could locate the actual Architecture Decision Records without asking someone named Priya to share a bookmarked link.

The document that finally had a reader

The team had tried ordinary documentation. There was a README.md, which described installing Node 16 and contained an ASCII logo of a fox. There was a wiki, access to which required joining the “Knowledge Champions” group, accepting an annual policy, and correctly guessing which SSO tenant was production. There were ADRs, but their template began with “Status: Proposed” and, through disciplined consistency, every ADR remained proposed forever.

Then came .clinerules/architecture.md, and suddenly the organization possessed a document with an audience. It said the service layer owns business logic, database access goes through repositories, and nobody should modify /legacy/billing because it is “scheduled for removal after the next migration, or the migration after that, depending on celestial conditions.” Unlike the wiki, this text was loaded into an active coding task. Unlike the README, it had consequences.

Cline supports workspace rules in .clinerules/ and .cline/rules/, combines those with global rules, and gives workspace rules precedence when they conflict. This creates the first governance mechanism in company history that can settle an argument about whether a preference is local or organizational: whichever markdown file is closer to the repository wins. Cline’s documentation recommends keeping rules focused by concern and concise because they consume context tokens, a phrase that has made several teams discover that “everything we know about software” is not a free dependency.

A practical starter constitution

Rook & Piston began with four files. This was considered modest because the company’s previous onboarding guide was a 46-slide presentation called FINAL_v12_use_this_one.pdf. The following structure makes the agent’s context more useful than a single all-purpose manifesto, while still preserving the soothing illusion that the team has finished deciding how it writes code.

.clinerules/
├── 01-project-basics.md
├── 10-architecture.md
├── 20-testing.md
└── 90-docs.md

01-project-basics.md contained the always-on rules: package manager, formatter, test command, and the sentence “do not add a dependency for one line of code.” This last requirement was immediately tested when the agent proposed a 3.7 MB library to left-pad a string, proving that values are only real when written down in a file with a leading zero.

The useful rule format is almost embarrassingly unceremonious: name the constraint, point to an existing good example, say why it exists if the reason is non-obvious, and provide a command that can verify the work. “Follow existing patterns” is an attractive instruction because it asks nothing of the author and nothing specific of the model. “For API errors, use src/lib/errors.ts; run pnpm test api after changes under src/api/” is less poetic, but it has a chance of being followed.

The YAML front matter that turned standards into zoning law

Then someone discovered conditional rules. Rather than loading frontend guidance while editing a database migration, Cline can apply a rule when files in the current context match paths glob patterns. In the resulting organizational redesign, the frontend team received a rule file, the backend team received another, and the docs team finally achieved the dream of being consulted only when someone was actually touching Markdown.

---
paths:
  - "src/api/**"
  - "src/services/**"
---

# API changes

- Keep route handlers thin; put business logic in services.
- Use the error helpers in `src/lib/errors.ts`.
- Run `pnpm test api` before reporting completion.
- Do not alter `src/legacy/billing/**` without an explicit request.

This is good at reducing irrelevant instruction load. It is bad at resolving ambiguity, reading minds, or detecting that the example in src/lib/errors.ts was written by an intern during a systems outage in 2023. Conditional matching uses the files in the prompt, open and visible editor tabs, files already edited during the task, and pending operations. A broad **/*.ts rule therefore does not express a principle so much as summon a weather system. Cline also fails open on invalid YAML, exposing the raw rule content instead of politely informing you that a missing colon has converted your governance program into decorative text.

The inevitable ratchet

Within three weeks, every agent surprise produced a new bullet. The agent changed a lockfile: add “never manually edit lockfiles.” It added a test snapshot: add “do not update snapshots unless behavior is intended.” It opened a pull request without a migration note: add a six-part procedure for migration notes, including a table for rollback conditions and a reminder that tables should not be used casually.

Soon the repository held 18 rules, 6 conditional scopes, and one appendix titled “Exceptions to the Exceptions.” The fictional Internal Prompt Office reported an unprecedented 14,000% increase in policy surface area, calculated by dividing one good instruction by zero previous instructions and then refusing to explain the denominator. The team was proud: it had finally converted years of tacit judgment into a portable, versioned asset that could be reviewed in a pull request and ignored with confidence.

This is where .clinerules is genuinely useful and where it becomes dangerous. It is good for stable, testable instructions: commands to run, directories that should not be touched, approved patterns with a file reference, and repo-specific constraints that otherwise get repeated in every task. It is bad as a landfill for every past incident, every style preference, and every argument someone did not want to have in code review. Rules are context, not enforcement; they can guide an agent, but they do not replace tests, branch protections, permissions, or a human review of a risky diff.

The maintenance ceremony nobody can skip

There is a small operational advantage to accepting the absurdity. Treat rules like production code. Keep team-shared rules under .cline/ or .clinerules/ in version control, keep secrets out of them, and review rule changes as behavior changes. Use cline config when you need to inspect or edit configuration from the CLI. Do not casually import global rules, hooks, skills, or plugins from strangers; Cline’s own configuration guidance notes that hooks and plugins can execute code and should be reviewed like executable artifacts.

At Rook & Piston, the wiki remains online, untouched, and technically authoritative. But the real standard now lives beside the code in short Markdown files, where it is visible to the tool that needs it and diffable by the people responsible for it. The joke is that the team had to hire a tireless text-prediction machine before it wrote down how the system works. The true observation is that a small, current, versioned set of project instructions is more valuable than a perfect document nobody opens.