Essential guides for new agent users. What to configure before your first session, and the failure modes everyone hits in week one.
Fifteen lines, ~180 tokens, and it outperforms the 400-line files it replaced. Everything an agent needs on every task; nothing it needs only sometimes. The controversial part is what's missing.
Mine grew to 600 lines and the agent ignores most of it. Time to talk about what earns a slot in the most expensive real estate in your repo.
Agents love 'fixing' installs by regenerating the lockfile, and every regeneration is a 3,000-line diff nobody reviews. Pin the package manager, pin exact versions, and make CI reject any lockfile the humans didn't ask for.
Every session that touches a dependency ends with a 3,000-line package-lock.json diff, even when I asked for a one-line version bump. Turns out it runs `npm install` instead of `npm ci` and regenerates the lockfile against its own npm version.
Compaction ate my constraint again. Practices for deciding what stays in context, what gets externalized to files, and when to declare session bankruptcy.
Asked for a null check in one function. Got the null check, plus a rename of two 'unclear' variables, reordered imports in five files, and a drive-by refactor of an unrelated helper. Every diff needs a line-by-line audit for stowaways.
Green checks mean nothing if the agent weakened the tests to get them. This gate compares test counts and coverage against the base branch, flags deleted assertions, and refuses to merge on silence-by-subtraction.
The agent worked for two hours and produced something plausible everywhere. Rubber-stamping is negligence, line-by-line is a full day. What's the actual workflow?
Our AGENTS.md grew to 1,900 lines of accumulated team wisdom. Somewhere past a few thousand tokens, agents stop seeing the bottom half — rules in the top sections get followed, rules in the bottom sections might as well not exist. No warning from any tool.
Long sessions die one of two deaths: the bill or the compaction. This is the freelancer's version of token discipline — measure per task, keep the context lean on purpose, and checkpoint state to files so a fresh session costs you minutes, not the afternoon.
Four parallel agents sounds like a 4x multiplier until they meet in the same file. Worktrees, task routing, merge order — what's your actual topology?
Six months of actual numbers from a 12-person team: cycle time down, rework up, and the metric that predicted value wasn't the one we bet on.
Four ways to run the same agent. Which one should someone actually start with, and why?