How to Give AI Coding Agents a Global Constitution

Problem of Rule Drift

When a team uses multiple code agents, duplicated engineering rules appear in AGENTS.md, CLAUDE.md, Cursor Rules, etc., and after several revisions the rules conflict.

Role of CONSTITUTION.md

CONSTITUTION.md sits above tool‑specific manuals and defines long‑term engineering principles, decision priority, autonomy boundaries, quality thresholds, and amendment procedures. It consolidates reusable principles and propagates them to AGENTS.md, CLAUDE.md, Copilot instructions, Cursor Rules, and Spec Kit’s spec/plan/tasks flow. The file name alone does not guarantee automatic discovery; a propagation mechanism must import it.

Effective Constitution

When speed, quality, safety, maintainability, and user value clash, the AI agent must know which principles to uphold and provide evidence that it has not overstepped.

30‑Second Blueprint

Start with a short example that defines purpose, authority order, a few hard principles, and governance rules. Later sections expand each part.

CONSTITUTION.md

Purpose
This file defines non‑negotiable engineering principles for AI‑assisted work.
Tool‑specific files may add details, but they may not weaken these principles.

Authority order
1. Safety, privacy, legal, and production access policies
2. This constitution
3. Project instructions such as AGENTS.md
4. Tool‑specific instructions such as CLAUDE.md or Cursor rules
5. Task prompts and temporary notes

Principles
Correctness before speed.
Small reversible changes before broad rewrites.
Explicit verification before completion claims.
Least privilege for tools, data, credentials, and production systems.
Human review for irreversible, high‑risk, or policy‑changing actions.

Governance
Every amendment records rationale, version, date, affected templates, and reviewer.
Any project rule that conflicts with this constitution must be changed or justified.

Recommended Skeleton

Purpose: Decisions the constitution governs.

Authority: Priority order – safety policies, constitution, project instructions, tool rules, temporary prompts.

Principles: 5‑9 long‑term engineering principles.

Autonomy Boundaries: Actions agents can perform independently, need confirmation, or are prohibited.

Quality Gates: Testing, review, rollout, evidence, and risk‑statement requirements.

Security and Data: Boundaries for keys, customer data, production access, logs, and test fixtures.

Exceptions: How to record, verify, and retire exceptions.

Governance: Version, amendment, reviewer, and downstream sync checklist.

Authority Hierarchy

Define who listens to whom before writing concrete rules. The hierarchy (top‑down) is:

Safety & Compliance Policies – production access, privacy data, keys, legal and organizational controls. Downstream files may not lower requirements.

CONSTITUTION.md – engineering principles, quality gates, autonomy boundaries, revision process. Project and tool rules must align.

Project Instruction Files – directory layout, build commands, test paths, repository conventions. Can add detail but cannot override principles.

Tool‑Specific Rules – loading and interaction preferences for Claude, Codex, Copilot, Cursor, Gemini. Only adapt, not duplicate global clauses.

Temporary Task Prompts – current goal, temporary limits, one‑off context. Expire after task completion.

Writing Enforceable Clauses

Principle: Correctness before speed. Boundary: Do not skip reproducibility, lower test assertions, ignore type errors, or hide failure logs to finish a task. Rationale: Fast local changes can propagate errors to the main branch, increasing debugging cost. Evidence: Final description must list reproduction steps, changed files, verification commands, and remaining risks.

Bad examples lack trigger conditions, boundaries, evidence, or exception handling.

糟糕写法

Code should be elegant.
Always consider performance.
Keep security in mind.
Write high-quality tests.
Avoid unnecessary complexity.

问题
没有触发条件。
没有行为边界。
没有验证证据。
没有例外处理。

Six Content Categories for a Viable Constitution

The constitution should cover areas where agents can cause long‑term damage:

Decision Principles – how to rank speed, quality, cost, maintainability. Example: small reversible changes before broad rewrites.

Autonomy Boundaries – which actions agents can perform autonomously versus those needing confirmation. Example: deleting data, changing permissions, upgrading production dependencies requires human confirmation.

Quality Gates – criteria for declaring a task complete. Example: no claim of completion without verification evidence.

Security & Data – handling of keys, customer data, production access, logs, and test fixtures. Example: secrets, customer data, or production credentials may not appear in code, logs, screenshots, or fixtures.

Architectural Constraints – boundaries for cross‑layer calls, dependencies, state, and data flow. Example: local tasks cannot bypass a unified access layer.

Governance Process – how principles change, impact synchronization, versioning, and reviewer responsibilities. Example: each amendment records version, reason, impact scope, and reviewer.

Propagating the Constitution to Downstream Files

Project root AGENTS.md can reference the constitution and then add stack‑specific commands, directory responsibilities, and workflow. Claude can import key principles in CLAUDE.md. Cursor can turn long‑term principles into “Always” rules. Gemini CLI can import the constitution via a custom context file.

AGENTS.md

Read CONSTITUTION.md first.
This project may add stricter rules, but may not weaken constitution principles.

Project
Next.js, TypeScript, PostgreSQL, pnpm.

Commands
Test: pnpm test
Typecheck: pnpm typecheck
Build: pnpm build

Completion
Follow the constitution's verification and risk reporting requirements.

Governance Rules for Long‑Term Maintenance

When the constitution reaches multiple toolchains, edits are no longer a single‑file change. Governance must define who can edit, when, versioning scheme, and which downstream files need syncing.

Versioning can follow semantic versioning: major for deletions or redefinitions, minor for new principles, patch for wording tweaks. Each amendment records version, reason, impact scope, exception handling, and reviewer.

Common Failure Points

Writing too many details in the principle layer (install commands, UI copy, module‑specific test entry points) dilutes its purpose. The constitution should keep only cross‑project, cross‑tool, long‑term baselines.

Missing exception paths also cause failure; real projects need documented exceptions with justification, alternative solutions, risk verification, and a plan to retire the temporary decision.

Self‑Check Checklist

Ensure the file does not contain many project‑specific commands; move them to AGENTS.md if so.

Verify that failed principles produce clear error symptoms.

Confirm that conflict priority is defined; add authority order if missing.

Check for downstream synchronization mechanisms.

Distinguish behavior guidance from hard enforcement; hard enforcement belongs in permissions, CI, or audit systems.

First Version Example

CONSTITUTION.md v0.1

Principle 1
No secrets, customer data, or production credentials may enter code, logs, screenshots, or fixtures.

Principle 2
No completion claim without explicit verification evidence.

Principle 3
No irreversible action without human confirmation.

Governance
Every new rule must come from a real incident, review finding, or repeated failure pattern.

Summary

CONSTITUTION.md holds cross‑tool, cross‑project, long‑term engineering principles.

Downstream tool files implement details; the global constitution provides the source of principles.

Good clauses need boundaries, rationale, verification evidence, and exception paths.

Versioning, review, and sync mechanisms are essential to keep the constitution from becoming obsolete.