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?

[devnomad-byte]

This question is exactly the tension I ran into while building a small multi-agent workflow initializer.

The model I ended up using is: do not make every file a peer source of truth.

For Cosmosmith, the split is:

• AGENTS.md is the canonical agent-facing project constitution and task protocol.
• CLAUDE.md, .cursor/rules/*.mdc, .github/copilot-instructions.md, .opencode/AGENTS.md, and .trae/rules/*.md are thin adapters that point back to the canonical rules.
• task.md is the operational ledger: claimed task, role, prompt, context, harness, loop, evidence, status.
• Proposal/design templates capture the product/spec layer before implementation.

Repo for reference: https://github.com/devnomad-byte/cosmosmith

My current view is that Spec Kit's constitution is most valuable when it stays above the agent-tool layer: product principles, quality bars, architectural constraints, non-negotiables, and review standards. AGENTS.md or tool-specific files are better for operational agent behavior: how to pick context, how to claim tasks, when to run tests, how to record evidence, when to ask for clarification, etc.

The DRY problem becomes manageable if one layer owns each concern:

• Constitution: enduring product/engineering principles.
• Spec artifacts: what is being built and why.
• Agent rules: how agents work inside this repo.
• Tool adapters: minimal pointers or format-specific glue.

What I would avoid is copying the whole constitution into every agent file, or copying Claude/Cursor/Copilot rules back into the constitution. That turns context engineering into sync debt.

The adapter pattern has been the cleanest compromise in my experiments: each agent gets a native entrypoint, but the real governance stays canonical and auditable. I would be interested in whether Spec Kit wants to recommend a similar boundary explicitly, because many teams are now juggling constitution.md, AGENTS.md, CLAUDE.md, copilot-instructions.md, Cursor rules, and task files at once.

[PeterDaumQS]

I do second that that view / separation of concerns.

Our constitutions define the long living slow changing principles.

Still though we include the constitution also in non spec driven coding related tasks, by advising the model via AGENTS.md (or similar) to read it always for such tasks. The token overhead / burden is minimal and justified by net effect, that these tasks also are guided by the principles of the constitution.

[mnriem]

We have formally disconnected agent context files from the Spec Kit process itself and now all commands reference the constitution. Note that we have done this because agent context files are specific to a coding agent. No need to copy the whole constitution into the agent context file.

Now you can safely put whatever you need for your coding agent in those agent context files and Spec Kit does not interfere with it

[mikedane-bitovi]

But wouldn't the agent still load the CLAUDE.md/AGENTS.md, etc., when it's using the spec kit skills/commands? Anytime the agent does anything, it loads those context files. So how can you meaningfully disconnect them from the Spec Kit process when they're loaded at the agent level?

Also note that for the most part now-a-days these agent context files are generally used in an agent agnostic way (Copilot reads CLAUDE.md, for example)

[mnriem]

There are really two separate questions tangled together in this thread, so let me split them.

Constitution vs. AGENTS.md / CLAUDE.md / copilot-instructions — they work differently. The agent context files are ambient: your coding agent injects them into essentially every request, so they continuously shape how the agent behaves. The constitution is on-demand: it isn't auto-injected anywhere. It only enters context because a command template explicitly tells the agent to read /memory/constitution.md at a specific step (spec, plan, tasks, etc.) for a specific purpose. That's also why there's no DRY conflict — they sit at different layers. Context files hold per-agent operating rules; the constitution holds project governance that the workflow consults at defined gates. You don't need to copy one into the other.

On "the constitution isn't used" — it's referenced by the commands, not embedded in the runtime. When you run a command like /speckit.plan, the command instructs the agent to load the constitution as part of that step. It genuinely gets read — but by the command, at that moment, rather than living permanently in context. And because it's the model reading a file on instruction (not the framework force-feeding it every call), how much of it gets pulled forward is the model's judgment: it weighs the relevant principles against the task instead of dumping the whole document every time. That keeps context lean, but it's also why it can feel absent if you expected it to be injected like AGENTS.md.

To be concrete about the current state: all of the workflow commands — specify, clarify, plan, tasks, implement, checklist, and converge — reference the constitution. specify loads it too, so it's consulted from the very first step.

[mikedane-bitovi]

That's a good, well-written explanation, thanks.

But that framing surfaces the issue more clearly for me, not less. You say the constitution is only loaded "at a specific step for a specific purpose", but AGENTS.md is also in context at that same step (because it's ambient). So during a /speckit.plan run, the agent has both files. The on-demand loading of the constitution doesn't create separation; both documents are simultaneously shaping the same request.

That brings me back to the core question, which I don't think has been answered yet: given that both files are in context during spec-kit commands, what content belongs in the constitution that you would explicitly NOT put in AGENTS.md?

The "project governance vs. per-agent operating rules" framing sounds clean. Still, in practice, every example of "project governance" I can think of (use BigInt for currency, follow TDD, RAII patterns, etc.) is something I'd also want in AGENTS.md. Hence, the agent follows it during normal coding sessions. If I only put it in the constitution, the agent ignores it outside of spec-kit commands. If I put it in both, I have sync debt.

A concrete example of a rule that clearly belongs in one and not the other would go a long way here.