Skip to content

Eleven Rules for Letting AI Agents Commit Code

agents-md is our open-source rulebook for AI coding agents: how Claude Code, Cursor and Codex should branch, commit, run CI and touch databases safely.

By NGMOB, published . 4 min read.

Key points

  • agents-md is an open-source, MIT-licensed standard from NGMOB that tells AI coding agents how to commit, branch, run CI/CD and change databases safely.
  • Its core is eleven rules: agents commit rarely on their own branches, ship one feature per squash-merged pull request, and deploy to production only from main.
  • Migrations run on a direct database connection, retries are capped, and work is tracked in issues that only a human can commit to.
  • It ships CLAUDE.md and AGENTS.md templates, five Claude Code skills and CI lint scripts, in English and Simplified Chinese.

Why AI agents need their own rules

AI coding agents produce code faster than Git workflows were designed to absorb. Wire Claude Code, Cursor or Codex straight into a repository and the same problems keep appearing:

  • GitHub API rate-limit storms
  • Runaway GitHub Actions bills
  • Unreadable history: hundreds of commits titled fix, wip or update
  • Deployment storms in production
  • Always-on database connections from short-lived agents
  • Schema migrations run through pooled connections, and breaking

agents-md is NGMOB's open-source answer: a standard in English and Simplified Chinese, with templates and Claude Code skills, that works as a compatibility layer between AI coding and ordinary Git workflows. Agents iterate quickly on their own branch while the shared system stays calm.

The eleven rules

  1. AI may modify frequently, but must commit infrequently.
  2. Never let an agent push directly to main; use ai/<feature> branches.
  3. One pull request is one feature, merged with squash, not merge commits.
  4. No full deploys on: push; use pull_request or workflow_dispatch.
  5. Production deploys come from main only; agent branches go to preview or staging.
  6. Migrations run on a direct database connection; the app runtime uses a pooled one.
  7. Aggregate schema changes rather than writing one migration per prompt.
  8. Search before generating: reuse existing components, utilities, schemas and prompts.
  9. No infinite retry loops: cap retries, surface the failure and ask a human.
  10. Event-driven, not polling; scale-to-zero is the default posture.
  11. Issues are the work record: start only Ready work, keep project status truthful, link pull requests, and leave new commitments to a human.

The full standard, STANDARDS.md, explains each rule across 19 chapters, from branching and commits to CI/CD, databases, agent behaviour, secrets, prompts, evals, observability and platform engineering.

What is in the repository

PathWhat it is
STANDARDS.mdThe full standard in one file, also in Chinese
docs/The same material split into chapters
skills/Five installable Claude Code skills
templates/Drop-in CLAUDE.md, AGENTS.md, workflow, CODEOWNERS and settings files
scripts/Bash lint scripts for commits, branch names, bilingual docs and links

The five skills load on their own when an agent needs them:

SkillLoads when an agent is about to
ai-native-git-workflowBranch, commit, push or open a pull request
ai-native-commitsWrite a commit message
ai-native-ci-cdEdit GitHub Actions or another CI workflow
ai-native-databaseEdit a schema, a migration or connection code
ai-native-agent-behaviorGenerate new code

Four ways to adopt it

Drop in the entry points. Claude Code reads CLAUDE.md; Codex, OpenAI agents and Cursor read AGENTS.md. Copy both templates into your repository root:

curl -L https://raw.githubusercontent.com/maweis1981/agents-md/main/templates/CLAUDE.md -o CLAUDE.md
curl -L https://raw.githubusercontent.com/maweis1981/agents-md/main/templates/AGENTS.md -o AGENTS.md

Install a skill. Copy a skill folder into .claude/skills/, and Claude Code loads it whenever its trigger matches.

Vendor the standard. Add the repository as a Git submodule, for example under docs/agents-md.

Enforce it in CI. Reuse the lint scripts, or the bundled commitlint config, so the rules hold even when nobody is watching.

For a reproducible setup, pin those URLs to a tagged release such as v0.2.0 instead of main.

The same idea, for business work

agents-md governs AI that writes code. Cadre applies the same thinking to AI that does business work, with citation checks, approvals and per-job costs; see Cadre: Digital Employees You Can Audit.

Questions

What is agents-md?

agents-md is an open-source standard from NGMOB for AI coding agents. It defines how agents such as Claude Code, Cursor and Codex should commit, branch, run CI/CD, handle database migrations and ship to production, and it ships templates, Claude Code skills and lint scripts that apply those rules.

What is the difference between CLAUDE.md and AGENTS.md?

Both are instruction files that coding agents read automatically from a repository. Claude Code reads CLAUDE.md, while Codex, OpenAI agents and Cursor read AGENTS.md. agents-md provides a template for each, and both point to the same standard.

Is agents-md free?

Yes. agents-md is free and open source under the MIT licence, published at github.com/maweis1981/agents-md in English and Simplified Chinese. The current release is v0.2.0, from June 2026.

Does agents-md only work with Claude Code?

No. The rules are tool-neutral and apply to any agent that commits to a Git repository. The installable skills are packaged for Claude Code, and AGENTS.md covers Codex, OpenAI agents, Cursor and similar tools.

Filed under agents-md, AI coding agents, Claude Code, Git.