Constitution vs AGENTS.md, copilot-instructions.md, CLAUDE.md, etc

[mikedane-bitovi]

I've seen this discussed a couple times before but the answers never really addressed my main concern. I don't really see a difference between the constitution in spec-kit and any of the other "context" files that are supported by the leading agent frameworks (AGENTS.md, copilot-instructions.md, CLAUDE.md, etc)

Are these files serving the same purpose? If so why do we need to constitution at all, it seems to me that including it just means that now we all need to keep our agent specific context files and the constitution in sync, which violates DRY principles outright.

So what exactly is the purpose of the constitution, and what are the best practices for using it in combination with the other context files? And tbh if the answer is "Just have the constitution point to your AGENTS.md" or vice versa, that seems completely unnecessary. Context engineering is becoming more and more important and a lot of care is placed in curating the right AGENTS.md/copilot instructions, so how does the constitution file fit into that process?

[mnriem]

The constitution file is loaded on-demand by the commands for establishing context and it does not mean it will always need the entire file. Whereas AGENTS.md, copilot-instructions.md, CLAUDE.md get sent with every request to the LLM irrespective of the context at hand

[mikedane-bitovi]

But how does that differ from something like skills, which are also loaded on demand?

I understand the mechanics of how it's loaded, but my question is more about the overlap in content. What specifically should go in the constitution vs the agent instructions files vs skills? Or should the constitution link to the other files?

Every time I generate a constitution file using spec-kit, the agent basically just replicates what's in the AGENTS.md file

[mnriem]

AGENTS.md is for how the agent is allowed to operate and what it can or cannot do and is dependent on your coding agent. Constitution are principles irrespective of that

[mikedane-bitovi]

Can you elaborate, please? That doesn't really answer my question...

According to the official AGENTS.md website the AGENTS.md file is

a dedicated, predictable place to provide the context and instructions to help AI coding agents work on your project.

In my experience, these files are for more than just telling the agent how it's allowed to operate; they provide information about project architecture, folder structure, dependencies, patterns, project scripts, and workflows. Basically, provide a high-level view of the environment the agent is operating in. I don't think the primary intention of AGENTS.md or CLAUDE.md or copilot-instrictions.md is to say what the agent is "allowed" to do...

When you say "Constitution are principles irrespective of that" can you be more percise? That seems to indicate that the Constitution should include everything other than what the agent is allowed to do?

I don't mean to be a pain here, just trying to understand. I teach spec-kit in trainings all the time, and by far the most common confusion among experienced developers is this. I'm not sure your answer really hit the mark

[gabrielisback]

In my understanding, "constitution" is meant to be applied to the set of specs/plans/tasks. It is NOT taken into LLM context.
While agents.md is for LLM context.

[mikedane-bitovi]

I’m struggling with the phrase 'NOT taken into LLM context.' If the LLM is the entity generating or validating the specs/plans/tasks, the constitution must be in the context window for that specific operation to be successful.

If the Constitution contains a rule like 'Use BigInt for currency,' but that rule is NOT in the AGENTS.md, doesn't that mean the agent will give me 'unconstitutional' code during a normal chat session? If the answer is to put it in both, how is that not a DRY violation? Could you provide an example of a rule that belongs in the Constitution but would be objectively wrong or harmful to include in AGENTS.md? Thanks!

[gabrielisback]

Sorry I was not precise. I meant, constitution is not send to LLM context in every conversation (e.g. later in implementation phase). Constitution is only send to LLM context when generating spec documents, e.g. when executing "/speckit-plan". - I think this is design intention (but might not yet fully implemented).
So if you want to ensure a rule like 'Use BigInt for currency' being followed - That sounds for all conversations, therefore it has to be defined in AGENTS.md, not constitution.md.

[mnriem]

During implement it is directed to read the constitution so it can adhere to it during iimplementation

[mikedane-bitovi]

Right, I understand that. My question is more about what to put in the Constitution vs the AGENTS.md file, because generally AGENTS.md also includes information about how to implement features, that's kinda the whole point. So are what's the point of the constitution? I feel like this is a simple question but maybe I'm not making sense?

If both the constitution and the AGENTS.md are loaded during implementation, what do we put in them, or are they just duplicates?

Can either of you provide an example of a constitution document and an AGENTS.md document that demonstrates what should be in each and how they coexist?

[GorkaCardona]

@mikedane-bitovi You are making perfect sense. I'm grabling with the same questions. I still don't feel it's been answered clearly. I'll post in this thread if I get to an answer, but right now constitution.md feels a bit over engineered.

Thanks for persisting on this question!

[nvwalj]

Helpful framings above. In practice as a daily Claude Code / Codex user, I find a clean separation:

• AGENTS.md = prescriptive rules. What to do, what not to do, conventions.
• CLAUDE.md = descriptive context. What this codebase is, who uses it, why decisions were made.
• Constitution / project charter = process meta-rules for specs/plans. Not LLM context.

In that frame the constitution doesn't compete with AGENTS.md — it sits one level above and constrains how specs are written, not how the LLM is conditioned each call. They DRY only if you collapse two distinct concerns.

Practical pain point not yet mentioned: the agent-written memory files (memory/YYYY-MM-DD.md, ~/.claude/projects/*.jsonl) drift fastest of all and are usually the dirtiest signal. Reviewing them weekly catches inferred-but-undocumented rules early.

Tangentially relevant since this thread is about the file ecosystem: I open-sourced AI Memory Reader, a free native macOS viewer for the whole constellation (AGENTS.md, CLAUDE.md, .codex/, .cursor/, .continue/, .aider/, etc.) — auto-discovers the agent directories, watches for live writes, renders in GitHub-style markdown. Built it because I got tired of opening these in TextEdit one at a time. Feel free to ignore if not your jam.

[mikedane-bitovi]

What is the difference between AGENTS.md and CLAUDE.md though? In my understanding, they're both doing the same thing, although CLAUDE.md is only read by Claude (and also Copilot funnily enough). But assuming you're using Claude Code then wouldn't it grab both AGENTS.md and CLAUDE.md on every request. You're implying that CLAUDE.md should say what the codebase is, who uses it etc, and then AGENTS.md is more prescriptive rules, but that doesn't make any sense to me... Wouldn't you just choose one of those files? Why the distinction when AGENTS.md is meant to be a drop in replacement for CLAUDE.md?

Also if you're using Codex as you mentioned, then wouldn't Codex not pick up the CLAUDE.md file? So you would end up losing all of your descriptive context?

[nvwalj]

@mikedane-bitovi you're right to push on that, and re-reading my comment I overclaimed. The prescriptive-vs-descriptive split isn't really a file-level distinction — both kinds of content end up in the same file in most setups. The actual reason there are two filenames in the wild is historical:

• AGENTS.md is the cross-tool convention (Codex, Aider, most OSS terminal agents support it)
• CLAUDE.md is the Anthropic-specific name; Claude Code reads it first, but also reads AGENTS.md if present
• Copilot reads .github/copilot-instructions.md, etc.

If you're only running one agent → pick one filename based on which agent. If you're running several → AGENTS.md as the single source of truth is the lower-friction path, and the agents that don't natively read it will at minimum tolerate a symlink to it.

So the cleaner framing is probably:

• File: pick one location per project. Default to AGENTS.md unless you need Claude-specific tricks that Codex would choke on.
• Content: mix prescriptive (rules, don't-do's) AND descriptive (architecture, glossary) — both are useful, they just answer different questions the agent asks itself.
• Constitution: as @gabrielisback / @mnriem said upthread, sits one level above and gates which specs are written how, rather than conditioning each LLM call.

On your Codex point: yes, you'd lose CLAUDE.md-only context. Practical fix is to keep the canonical file as AGENTS.md and have a one-line CLAUDE.md that just says "see AGENTS.md", or symlink. That way Claude-only sessions still find it without duplication.

Apologies for the lazy distinction in my earlier comment — your read of it as "wouldn't you just choose one" is correct.

[davesharpe13]

@nvwalj mentioned "constrains how specs are written" but constitution isn't loaded on specify, it is on plan and tasks. For me, I like your thinking and I do have spec rules in my constitution. I keep a memory (!!) to load the constitution during specify. BTW I keep AGENTS as general rules (the contract, slightly expanded version of Karpathy's 4 point AGENTS). CLAUDE.local.md as my personal specialized rules (not much more than Karpathy) and constitution as my nitty gritty specifics (referred to by AGENTS ! but with a "gate" so that it isn't always loaded, e.g.,, for specify it has rules about TDD and research, for plan/tasks/implement it has stuff about RAII, for implement it has stuff about pre/linting).

[nvwalj]

@davesharpe13 the per-phase gating insight is the missing piece for me. I had constitution as "global meta-rules" but the way you've structured it (specify-gate = TDD + research, plan/tasks-gate = RAII, implement-gate = lint/pre) means each phase only sees the rules it can act on. That's actually cleaner than loading everything every call.

The CLAUDE.local.md split also clarifies something I've been working around. I'd been jamming personal preferences into ~/.claude/CLAUDE.md (global) and project conventions into /CLAUDE.md — but committed-but-personal as a third layer solves the "this is my preference, not the team's" problem I'd otherwise been resolving with git stash or .gitignore tricks.

One observation that compounds with your framing: the further down the stack a file lives (constitution → AGENTS → CLAUDE → CLAUDE.local → memory/*.md), the faster it drifts. Memory files specifically (Claude Code's ~/.claude/projects/*.jsonl session transcripts, Codex's ~/.codex/sessions/) drift hourly — they capture every mid-session correction but never get pruned. Periodically reading them is where I catch the rules that should have been promoted up the stack into AGENTS / constitution.

That's a chunk of why I built AI Memory Reader — the chunked JSONL viewer for session transcripts is where the actual drift surfaces, not the static markdown files. Free + open source, mostly because I got tired of vim choking on multi-MB session logs.

Curious — anyone here doing constitution updates by mining patterns out of session logs, or is it still all manual?