Project Governance and Memory

Project Governance and Memory

Spec-Driven Develop treats project instructions and durable memory as first-class workflow surfaces. This is important because long-running agent work often spans multiple sessions, tools, and platforms.

The workflow separates instruction surfaces from memory surfaces.

Instruction Surfaces vs. Memory Surfaces

Surface Type	Purpose	Examples
Instruction surface	Rules that guide the agent during work	AGENTS.md, CLAUDE.md, .cursor/rules/, .windsurf/, .clinerules*
Memory surface	Durable project facts, recurring gotchas, and decisions that should survive sessions	Active agent's native project memory, or explicit repo-local fallback only when selected

The workflow should not silently create competing truth sources.

AGENTS.md

AGENTS.md is the shared instruction surface for Codex, Cursor, and other Markdown-aware coding agents.

It should contain:

• Repository scope.
• Truth sources.
• Development rules.
• Validation commands.
• Security and testing expectations.
• Stable agent-facing constraints.

CLAUDE.md

CLAUDE.md is the Claude Code-specific instruction surface.

It should:

• Point back to AGENTS.md for shared rules.
• Contain Claude Code-specific reminders only.
• Avoid duplicating general policy.
• Stay aligned with AGENTS.md when shared rules change.

Platform Rule Files

The workflow inventories existing platform rule files before editing:

• .cursor/rules/
• .windsurf/
• .clinerules*
• .codex/
• Other equivalent project-level rule surfaces.

Existing rules should be preserved. Conflicts should be recorded and surfaced, not silently overwritten.

Native Memory First

Durable project facts should use the active coding agent's native project memory mechanism when available.

Examples of facts worth recording:

• A recurring test command or setup requirement.
• A build gotcha that future agents are likely to hit.
• A stable architecture invariant.
• A repository-specific release rule.
• A decision about where project governance lives.

Repo-Local Fallback Memory

A repo-local memory file should only be used when:

• The project already declares one, or
• The user explicitly selects one, or
• The workflow records that no native memory surface is available and a fallback was approved.

The workflow should not invent docs/project-memory.md as a default source of truth.

Governance Resolution Output

During Phase 4, the workflow records the resolved surfaces in docs/progress/MASTER.md.

The record should answer:

• Which file contains shared agent instructions?
• Which file contains Claude Code-specific instructions?
• Which platform rule files exist?
• Is native project memory available?
• If no native memory exists, was a repo-local fallback approved?
• Where should future durable facts be recorded?

Related Pages

• Spec-Driven-Develop-Workflow
• GitHub-Issues-Projects-and-PRs
• FAQ