Write .clinerules for the Moments Your Coding Agent Usually Goes Off-Track

Write .clinerules for the failures you’ve already had to review: broad rewrites, skipped tests, invented conventions, and an agent that treats “fix the bug” as permission to renovate half the repository. Keep the always-on rule short, make every instruction testable, and move task-specific process into toggleable files or workflows instead of turning one Markdown file into your internal engineering handbook.

Start with a workspace baseline, not a personal manifesto

Create .clinerules/ at the repository root and commit it. Cline’s workspace rules are project-local, while global rules live outside the repository; the point of the workspace copy is that a fresh clone gives every engineer—and every agent—the same constraints. Cline’s Rules UI can create and toggle individual Markdown rule files, so a directory is more practical than a single ever-growing blob.

mkdir -p .clinerules
cat > .clinerules/00-baseline.md <<'EOF'
# Repository baseline

- Inspect the nearest existing implementation before adding a new pattern.
- Keep changes limited to files required by the requested behavior.
- Do not change public APIs, database schemas, lockfiles, or CI configuration unless the task explicitly requires it.
- Before editing, state the files you expect to change and why.
- Before finishing, run the narrowest relevant validation command. Report the command and its result.
- If validation cannot run, say what blocked it; do not claim the change is verified.
EOF

That’s deliberately boring. It tells Cline what evidence to collect, what kinds of scope expansion require consent, and what a finished task must include. It does not tell the agent to “write clean, scalable, production-ready code,” because none of those phrases gives you anything to review. Cline’s own guidance makes the same practical distinction: rules should capture implementation constraints and standards, not become an exhaustive manual.

Use rules that point to local evidence

The most durable rules name a file, a command, or a boundary that exists in the repo. Replace generic preferences with instructions Cline can verify without guessing. If your team has a formatter or test target, put the literal command in the rule. If the command is too slow for every small change, say when it applies.

• Weak: “Write comprehensive tests.” Better: “For changed code under packages/api/, add or update a Vitest case when behavior changes. Run pnpm --filter @acme/api test before finishing.”
• Weak: “Follow our API conventions.” Better: “New HTTP endpoints belong in apps/api/src/routes/; use the response helpers in apps/api/src/http/respond.ts; do not return raw ORM records.”
• Weak: “Be careful with migrations.” Better: “Do not generate or modify files in db/migrations/ unless the user explicitly asks. If a schema change is necessary, stop after proposing the schema and migration plan.”
• Weak: “Don’t make unrelated changes.” Better: “Do not reformat untouched files, reorder dependency manifests, or update generated snapshots unless they are part of the requested fix.”

You’ll notice that these rules don’t try to predict every decision. They reduce ambiguity where ambiguity has cost you time. A rule that names the established response helper beats 20 lines of prose about consistency, especially for a model that has not yet found the relevant code path.

Split permanent constraints from temporary operating modes

Keep 00-baseline.md enabled for nearly everything. Then add smaller rules for work that happens occasionally: frontend work, migrations, incident fixes, or a release branch. Cline supports toggling rule files in its Rules popover; when a rule is enabled, its contents are appended to the system prompt. That makes task files useful, but it also means leaving every specialized file enabled makes the agent carry irrelevant instructions on every turn.

# .clinerules/20-frontend.md
# Enable for UI work only.

- Reuse components from `apps/web/src/components/` before creating a new primitive.
- Use the tokens in `apps/web/src/styles/tokens.css`; do not introduce literal colors or spacing values when a token exists.
- For changed interactive behavior, run `pnpm --filter @acme/web test`.
- For changed layouts, include the route and viewport sizes that need manual checking.

This is also where a lot of .clinerules files go bad. A 600-line “always on” file doesn’t create discipline; it creates competing instructions and burns prompt space explaining rules unrelated to the task. Cline explicitly distinguishes rules from workflows: rules are added to every system prompt, while workflows are invoked on demand. If you need a six-step release procedure, a PR-review checklist, or a migration ritual, write a workflow rather than attaching it permanently to normal coding.

Make the agent stop before irreversible work

Rules are guidance, not an authorization system. They’re good at getting a plan, a test command, or a confirmation question into the normal loop. They are not the right control for enforcing security boundaries. Cline also has Hooks for executable, project-specific logic; hooks can receive operation context and return a cancellation decision. Use that when a forbidden command or path must be blocked rather than merely discouraged.

For ordinary repositories, put the consent boundaries directly in the baseline rule. Be explicit about the things that silently create operational work: migrations, dependency upgrades, deployment files, secrets, external calls, and destructive commands. A good default is “inspect and propose first; wait for explicit approval before changing it.” That keeps a routine fix from becoming a surprise infrastructure change.

## Approval boundaries

Ask before:
- adding, removing, or upgrading dependencies
- modifying `infra/`, `.github/`, deployment manifests, or CI workflows
- changing database schema or migration files
- running commands that delete data, reset state, or call production services

Never read, print, or commit values from `.env*`, credentials files, or secret stores.

Give Cline a concrete finish line

“Run tests” is a start, not a finish line. Tell Cline what to do when the command fails, takes too long, or is unavailable. Otherwise it may spend several turns repairing unrelated failures, or it may report a task complete after only type-checking. The final response rule below keeps the report useful during review without forcing a verbose changelog for every two-line fix.

## Completion

Before finalizing:
1. Run the narrowest validation relevant to the changed code.
2. If it fails because of the change, fix it or explain why a fix needs approval.
3. If it fails for a pre-existing reason, report the exact failing command and relevant failure.
4. Summarize changed files, behavior changed, validation run, and remaining risk in four bullets or fewer.

Don’t use this to demand green CI when local validation takes 18 minutes or needs credentials the agent cannot have. Put the quick command in the rule, and leave slower integration checks to CI. The purpose is a reliable handoff: you should know what changed, what was executed, and what still needs a human decision.

Review the rule file like production configuration

Ask Cline to create a draft with /newrule if it helps it inventory existing patterns, but review the result yourself. Cline’s /newrule feature can analyze the workspace and create the rule file; that’s a convenient first pass, not proof that the generated standards are accurate. The agent is especially likely to over-generalize from one nearby implementation.

After three or four real tasks, delete what didn’t change behavior. If Cline keeps missing one rule, tighten it with a path, command, example, or approval boundary. If the rule only matters during a release, move it into a disabled task file or a workflow. The target isn’t a comprehensive prompt. It’s a small, versioned operating agreement that prevents the same review comments from happening again.