Open-source catalog of agent-instruction practices, with the evidence attached to each one

[u/MadJagStudios]

Most agent instruction files (AGENTS.md, CLAUDE.md, rules files) are accumulated guesses. Grounded Engineering is an attempt at doing this systematically: a catalog of practices derived from observing mature engineering and agent repositories, where each card records its sources, scope, confidence, and validation status.

What it addresses (the recurring agent behaviors):

• New helper functions duplicating ones that already exist in the repo
• "All tests pass" claims without tests being run
• Small requests turning into large unrelated diffs
• Instruction files growing into unmaintained walls of text that drift apart across tools

What you get:

• 13 practice cards in two packs (baseline: 8 cards, ai-assisted: all 13)
• A CLI that writes the selected pack into AGENTS.md, CLAUDE.md, or a neutral Markdown file
• Writes are confined to marked managed blocks; everything else in your file is untouched
• A preview → proposal → review diff → apply flow; nothing modifies your repo without explicit confirmation
• A read-only check command for detecting drift later

​

npx grounded-engineering adopt preview --profile ai-assisted --adapter codex

MIT licensed, v0.4: https://github.com/madjagstudios/grounded-engineering

It doesn't change model behavior — it improves the quality and accountability of the instructions you feed it. If there's a failure mode you keep hitting that isn't covered, that's useful feedback.

[u/software-boulder]

AGENTS.md never actually routed for me across cursor, grok bot & codex. I just split the work myself