openspec-context-docs

Separate normative requirements by placing testable rules in a spec.md file and moving narrative context to associated files like context.md or rationale.md, ensuring specification clarity without duplicating requirements.

A context.md file should capture purpose, design rationale, security considerations, constraints, failure modes, operational notes, and example request or response payloads to enrich the API specification.

Specification documentation mixes these when a two-layer separation is not enforced; moving narrative context into context.md and keeping strict requirements in spec.md prevents duplication and maintains testability.

Document design decisions and constraints in associated context files like rationale.md, detailing the purpose and failure modes to support onboarding while keeping the primary spec strictly normative.

You need separate context files when your specification requires comprehensive onboarding materials and change artifacts, ensuring stakeholders understand the rationale without cluttering testable requirements.

Yes, OpenSpec context documentation adheres to a sync rule that promotes stable context into the main specification, preventing the duplication of established requirements across files.