I’m a solo product owner, not a software engineer, and I don’t read code fluently. I use Codex and other coding agents to build both private tools and public products.
My previous approach was to paste one large Markdown file into every repository and tell the agent to follow it. Over time, I found several problems:
- Generic instructions were applied too rigidly.
- Agents sometimes guessed commands, paths, or project state.
- Applying the instructions could turn into an unnecessary full-project audit.
- Temporary milestones and release details polluted durable guidance.
- Different tools encouraged duplicated instruction files that eventually drifted.
- Model-routing advice could interrupt work instead of saving tokens.
I created the Pragmatic AI Engineering Manifest to address this.
It is not a universal AGENTS.md template. You place the manifest in an empty or existing repository and send:
The agent should then:
- Inspect only enough repository evidence to understand the project accurately.
- Create or repair a concise, project-specific root
AGENTS.md.
- Detect project use, data consequence, operational reach, and task risk independently.
- Wire only the AI tools actually used by the project.
- Continue the original task instead of turning setup into a ceremony.
The framework is intended to work whether the project is new or mature, personal or shared, private or public. It distinguishes local implementation, automated verification, owner acceptance, activation, and post-activation observation.
It also tells agents to:
- Never claim tests, inspection, or success that did not happen.
- Preserve existing work.
- Research material unknowns using authoritative sources.
- Challenge weak product or architecture assumptions.
- Require explicit authority for consequential actions.
- Keep model recommendations advisory and capability-based.
- Target a generated root
AGENTS.md below 120 lines or 12,000 characters.
For Claude Code, it keeps AGENTS.md canonical and uses a minimal CLAUDE.md import bridge rather than duplicating the instructions.
I refined it against three substantially different real repositories: a Windows hardware-facing desktop tool, a private multi-tenant operations system, and a publicly distributed local-first desktop app. The repository contains fictionalized, sanitized examples derived from those cases.
Important limitation: this is behavioral guidance, not enforcement. It does not replace permissions, sandboxing, backups, CI, access controls, or qualified security review.
This is a v0.1.0 public preview, released under MIT:
https://github.com/builtbyperez/pragmatic-ai-engineering-manifest
I would genuinely appreciate strict feedback rather than compliments:
- Which rules are too vague or too restrictive?
- What is still wasting context?
- Does it produce useful guidance with faster or weaker models?
- Are any compatibility claims incorrect?
- What happens when you apply it to an unfamiliar repository?
If you test it, please mention the coding tool, general project type, and size of the generated AGENTS.md. Please sanitize anything private before sharing.