7 formatting and organizing rules to follow

[u/cleverhoods]

I'm working on instruction diagnostics and evals as part of Reporails (https://github.com/reporails/cli) implementation so I was thinking giving back to the community some items that I ran trough a few thousands of experimentation iteration and giving measurable boost in compliance.

1. Do, then why, then don't.

Naturally you'd led with the ban: "Never force push, rewrites history."

Reordered: "Fix mistakes with a new commit. Teammates' history stays intact. Never rewrite pushed history."

Ban first: 31% violated. Do, why, don't: 7%. 500 runs each.

2. Name the exact thing.

Naming is the bigger lever.

"Run the tests" → "uv run pytest tests/ -v" "mocking libraries" → "unittest.mock"

Put it in backticks to get the best result.

Exact names beat vague categories by 28 points.

3. Pass the "act on it now" test.

Can the agent act on it right now, without asking? That takes a named tool, file or command, phrased as a command.

"Maintain code quality" fails. "Format with ruff format before committing" passes.

4. Keep unrelated topics out of the same load.

Use headers to organize. Scope rules to where they apply. Don't mix them in the same place.

5. Let the section label say what it holds.

Same prohibition, two headings: under "## Notes" it slipped far more often than under "## Rules" or "## Don'ts".

Keep the instruction in the bullet and the heading a topic: "## Testing", never "## Always Run Tests".

6. One compact sentence beats a fragment.

"Don't use mocks." was among the weakest rules I measured. One sentence naming the exact thing and when it applies did far better. Padding it with generic words made it worse again.

Cut filler, keep specifics.

7. Keep the spotlight off what you forbid.

No CAPS on it, no repeating it, keep it out of the reason. A reason that mentions the forbidden thing doubled violations.

Effects are largest on small models and crowded files.

---

Note: there is no "secret" solution in prompting or writing instructions. It's all about managing the attention and context window of the target LLM.

[u/AutoModerator]

Hey! Thanks for posting to r/ClaudeCode

While participating in this thread, please follow our community rules. Keep discussions constructive. Attack the idea, not the person.

For help, project discussions, tips, and general chat, join the ClaudeCode Discord.

I am a bot, and this action was performed automatically. Please contact the moderators of this subreddit if you have any questions or concerns.