AGENT.md vs codespec config file?

[fkromer]

From the docs it's not clear to me ...:

• Does openspec support both, context provisioning options: AGENT.md and openspec/config.yaml. What is the recommended option (potentially depending on usage scenario)?
• Will openspec support both context provisioning config options in the future?
• How differ both options related to openspec features? What are the pros and cons of one over the other option?

[starkmarkus]

My understanding is that these are not exactly the same kind of context mechanism.

AGENTS.md is mainly agent-facing guidance. It is useful for instructions that the coding assistant should read and follow, for example project conventions, workflow rules, review expectations, or “how we use OpenSpec in this repo”.

openspec/config.yaml is more of a structured OpenSpec configuration file. I would expect it to be used for settings that OpenSpec itself can parse reliably, validate, and use across commands/tools.

So I would not treat them as direct alternatives. The split I would use is:

• use AGENTS.md for human/agent-readable instructions and workflow conventions
• use openspec/config.yaml for machine-readable OpenSpec configuration
• avoid putting critical structured config only in prose, because agents may interpret it inconsistently
• avoid putting long guidance only in YAML, because it is less readable and less portable across tools

In practice, I think the best setup is probably both:

1. keep OpenSpec’s actual configuration in openspec/config.yaml
2. keep repo-specific agent instructions in AGENTS.md
3. make AGENTS.md point the agent to the OpenSpec workflow and config rather than duplicating everything

I am not sure what the long-term support policy is, so it would be good for maintainers to clarify whether both are intended to remain supported. But conceptually, I think they serve different purposes: AGENTS.md is context for the agent, while openspec/config.yaml is configuration for OpenSpec.