Configuring a CLI Agent With a Project File

Here's a finding that surprises most people the first time they measure it: the longer your agent config file gets, the less the agent follows it. Teams keep adding rules to their CLAUDE.md or AGENTS.md every time the agent does something they didn't like, the file swells to four hundred lines, and adherence drops. A short, sharp config file gets followed closely. A sprawling one gets treated as background noise the agent skims and mostly ignores. When people set up a cli agent config file, they optimize for completeness. They should be optimizing for the opposite.

This case study follows a team that learned that the hard way, and the fix that turned their ignored config into one the agent actually respected.

The Problem the Team Faced

A platform team at a logistics company adopted a terminal agent across a large TypeScript monorepo. Every time the agent did something off — used the wrong test runner, put files in the wrong directory, imported a deprecated utility — someone added a line to the project config file. Within two months the file was over three hundred lines of accumulated rules, conventions, warnings, and exceptions.

<!-- CLAUDE.md, circa month two: a wall of rules nobody could keep straight -->
# Project conventions
- Use pnpm not npm
- Tests go in __tests__ next to the file
- Use the internal logger, not console.log
- ... 90 more bullets ...
- Prefer composition over inheritance except in the legacy adapters
- ... 40 more nuanced exceptions ...

What this does: Documents every convention the team ever wanted, in one enormous file. It reads like thoroughness. In practice, the agent's adherence to any single rule got worse as the file grew, because the important rules were now buried among dozens of minor ones with equal visual weight.

The symptom that finally got their attention: the agent kept using npm despite pnpm being rule number one. The rule was there. It was just drowned.

The Wrong Approach

The wrong instinct is to treat the config file as documentation — a place to record everything true about the project. It isn't documentation; it's a set of instructions competing for the agent's limited attention. Every low-value rule you add dilutes the high-value ones. A config file that says everything effectively says nothing, because the agent can't tell which of your three hundred bullets are the two that actually matter for this task.

<!-- Wrong: piling on more rules to fix a rule-following problem -->
# IMPORTANT: ALWAYS use pnpm. THIS MEANS YOU. DO NOT use npm. EVER.
- (rule now shouting, still buried among 300 others)

What this does: Tries to fix poor adherence by adding emphasis and repetition to one rule, while the underlying problem — too many rules competing for attention — gets worse. Shouting doesn't help when the real issue is signal-to-noise. The team was treating a volume problem as an emphasis problem.

⚠️ Common mistake: Growing the config file every time the agent misbehaves. Each addition feels like progress and collectively makes the file less effective. A cli agent config file is not a changelog of every mistake — it's a curated set of the rules that matter most, and curation means removing things, not only adding them.

The Correct CLI Agent Config File Approach

Three changes turned the logistics team's config around.

First, ruthless prioritization. They cut the file to the fifteen rules the agent actually kept breaking or that mattered most for safety and correctness. Everything else — the nuanced style preferences, the rarely-relevant exceptions — came out. A short file the agent follows beats a complete one it ignores.

<!-- CLAUDE.md, rebuilt: short, specific, imperative -->
# The rules that matter here
- Package manager: pnpm. Never npm or yarn.
- Run tests with `pnpm test:unit` before claiming a change works.
- Never edit anything under `/generated` — it's built from proto files.
- Logging: import from `@co/logger`, never console.log.
- New endpoints need a matching test in the same PR.

What this does: Gives the agent a handful of high-value, imperative, specific rules it can actually hold in attention at once. Each one is either a safety boundary or a convention the agent had repeatedly gotten wrong. The signal is no longer buried, so adherence jumps.

Second, they made rules specific and testable rather than vague. "Write clean code" is unfollowable; "run pnpm test:unit before claiming a change works" is a concrete instruction the agent can execute and you can verify.

Third, they layered configs by scope. A short root file held the repo-wide rules; per-service files held rules specific to each service, so an agent working in the billing service saw billing's conventions without wading through everyone else's.

[object Object],
,[object Object], CLAUDE.md                    ,[object Object],
,[object Object], services/billing/CLAUDE.md   ,[object Object],

What this does: Scopes rules to where they apply, so the agent working in a subdirectory sees a small, relevant rule set rather than one giant global file. Local relevance keeps each file short and each rule pertinent, which is what keeps adherence high.

⚡ Pro tip: When you're tempted to add a rule, first check whether an existing one can be made clearer instead. Most adherence problems are vague-rule problems, not missing-rule problems. Sharpening "use the right logger" into "import from @co/logger, never console.log" fixes more than adding a fourth rule about logging ever would.

What Actually Belongs in the File

The prioritization question gets easier when you know the categories that earn a place. Three kinds of rule justify space in a config file, and a fourth kind that people love to add doesn't.

Safety boundaries earn the top spot: the directories the agent must never edit, the commands it must never run, the data it must never touch. A miss here is expensive, so these come first and are phrased as hard prohibitions.

Project-specific facts the agent can't infer earn a place next: your actual test command, your package manager, where files go, which internal library to import. The agent has no way to know your team chose pnpm or that logging goes through @co/logger — that's exactly the information a config file should carry.

Repeatedly-broken conventions earn the last slots: the specific things this agent keeps getting wrong in this repo. If it never confuses your test runner, you don't need a rule about it; if it does, that rule earns its line.

What doesn't belong is generic best practice the model already knows. "Write readable code," "handle errors," "add comments" — the agent knows these, and spending config space on them dilutes the rules that carry real information. Every generic rule you cut makes a project-specific one more visible.

<!-- Earns a place: specific, project-only, unguessable -->
- Feature flags: read from `@co/flags`, never process.env directly.
<!-- Does NOT earn a place: generic, already known -->
- Write clean, maintainable code with good error handling.

What this does: Contrasts a rule that carries information the agent couldn't have known with one that restates general knowledge. The first changes behavior; the second is filler that dilutes the file. Keeping only the first kind is what keeps the config sharp.

⚡ Pro tip: Before adding any rule, ask "could the agent have known this without being told?" If yes, it's probably generic knowledge that doesn't belong in the file. Reserve the config for the unguessable, project-specific facts and the boundaries that matter — that's the information only your file can provide.

Results and What Changed

After the rebuild, the agent used pnpm consistently — the rule that had been buried at line one of three hundred was now line one of fifteen, and it stuck. Across the board, adherence to the surviving rules improved sharply, precisely because there were fewer of them competing. The team's instinct had been backwards: they'd been adding to fix adherence, when subtracting was the fix. What made it stick was the budget — without a hard cap the file would have crept back up within weeks, because the urge to add a rule after every small annoyance never really goes away.

The deeper shift was treating the config file as a living, curated artifact with a budget. They set an informal cap — if adding a rule meant the file exceeded roughly twenty lines, an existing rule had to earn its removal first. That budget forced the prioritization that made the file work.

⚡ Pro tip: Periodically ask the agent itself which rules in your config are ambiguous or seem to conflict. It'll often flag exactly the vague or contradictory rules that are quietly hurting adherence, and you can sharpen or cut them. The config file is one of the few documents whose reader can tell you where it's failing.

⚡ Pro tip: Put safety boundaries — the "never touch /generated" class of rule — at the top and phrase them as hard prohibitions. Those are the rules where a miss is expensive, so they earn the most prominent, least ambiguous position in the file. Correctness conventions can follow; the boundaries come first.

How to Apply This to Your Situation

A startup with one repo and a small team: a single short root config with your ten most-broken conventions. Add to it only by trading out a weaker rule, and revisit it monthly.

A large enterprise monorepo: a lean root file for org-wide non-negotiables, layered with per-service files for local conventions, plus an enterprise-managed policy layer for the rules that can't be relaxed by any individual.

An open-source maintainer accepting agent-assisted contributions: a short, public config that tells contributors' agents your must-follow conventions, so a drive-by agent-generated PR at least respects your test and style boundaries.

Next Steps

An effective cli agent config file wins by curation, not accumulation. Keep it short, make every rule specific and imperative, put safety boundaries first, layer by scope, and treat it as a living document with a budget rather than a changelog of grievances. The logistics team's file worked the day they started removing rules instead of only adding them.

The rule sets that work — the lean root conventions, the per-service overrides, the safety-boundary phrasing — are patterns you'll reuse in every project. Save your config templates in PromptABCD so your next repo starts with a tight, effective file instead of the three-hundred-line wall the agent learns to ignore.