Spec-Driven Development / Agent-Driven Development

Make the repository the context system, not the prompt.

SpecNative Development is a development model where specifications, architecture rules, conventions, and decisions live in stable repository files so agents can plan and implement work with less runtime ambiguity.

Understand the model Use it with agents

Specification-first instead of prompt-first
Repository-native context instead of session-local context
Works with Codex, Claude Code, OpenCode, and similar agents

Product Problem, users, goals

Architecture Boundaries and constraints

Specification Required behavior

Tasks Executable plan

prompt => select spec, not explain project

Concept

What changes in a SpecNative workflow

The shift is straightforward: instead of rebuilding project context inside a conversation, the repository encodes the context once and the agent navigates it deterministically.

Prompt-centric workflow

User describes the feature and the project state in a prompt.
Agent reconstructs context from chat history and partial file reads.
Important constraints may be omitted, duplicated, or outdated.
Next session often repeats the same explanation.

Repository-centric workflow

User requests work against an existing spec or initiative.
Agent reads repository navigation and source documents.
Architecture, conventions, and decisions already exist as inputs.
Each session starts from the same durable context surface.

Execution model

Intent becomes a specification. Specifications are decomposed into tasks. Architecture and decisions constrain the plan. Code and tests realize the result.

Motivation

Why teams adopt this model

Prompt engineering does not scale

Long prompts become a brittle substitute for architecture, decisions, and operational rules that should already exist in version control.

Context is usually transient

Agents often inherit shallow session state instead of stable product and system context with explicit ownership.

Repositories are not AI-native by default

Source layouts optimize for code storage, not for deterministic navigation, decision tracking, or specification lookup.

Repeated explanation wastes time and tokens

Teams repeatedly restate the same product rules, architectural boundaries, and coding conventions across sessions.

Structure

Repository layout for agent-guided work

The repository template in this project keeps most context under agents/. In larger systems, the same model can be expanded into dedicated specs/, tasks/, architecture/, and workflows/ areas.

repo/
├── AGENTS.md
├── README.md
├── agents/
│   ├── README.md
│   ├── PRODUCT.md
│   ├── ARCHITECTURE.md
│   ├── STACK.md
│   ├── CONVENTIONS.md
│   ├── COMMANDS.md
│   ├── DECISIONS.md
│   ├── SPEC.md
│   └── specs/
│       ├── README.md
│       └── authentication/
│           ├── README.md
│           ├── SPEC.md
│           └── TASKS.md
└── workflows/
    └── implementation.md

Navigation files

README.md files route both humans and agents to the correct context instead of duplicating all project knowledge.

Source documents

Files such as PRODUCT.md, SPEC.md, ARCHITECTURE.md, and DECISIONS.md hold the durable truth.

Execution artifacts

Task files or task sections break specs into implementable units and connect them to validation.

Reading strategy

Agents should navigate, not ingest the whole repository. Start with local navigation, then load only the documents needed for the current task.

Runtimes

How to use the method with OpenCode, Claude Code, and Codex

SpecNative is not tied to one agent runtime. The repository is the stable layer. The runtime is the execution layer. The integration pattern is to give each tool a thin bootstrap into the same repository context.

OpenCode

Terminal, desktop, IDE

OpenCode provides primary and subagents, configurable permissions, and ACP/editor integrations. It fits well when you want plan/build separation around a repository-native workflow.

Recommended pattern

Use a plan-style agent to read specs and propose work without edits.
Use a build-style agent to implement once the spec and task path are clear.
Keep repository rules in AGENTS.md and folder README.md files.
Restrict write and bash permissions until the reading path is validated.

{
  "$schema": "https://opencode.ai/config.json",
  "agent": {
    "plan": {
      "permission": {
        "edit": "deny",
        "bash": { "*": "ask" }
      }
    },
    "build": {
      "permission": {
        "edit": "allow",
        "bash": { "*": "ask", "git status *": "allow" }
      }
    }
  }
}

Source: OpenCode agents and permissions docs

Claude Code

CLI and agent teams

Claude Code reads a root CLAUDE.md, supports custom commands, hooks, MCP, and multiple agents. In a SpecNative repository, use CLAUDE.md as a bootstrap file rather than a monolithic project manual.

Recommended pattern

Create a short CLAUDE.md that points to AGENTS.md and the local navigation model.
Store real project truth in versioned context files, not in one giant instruction file.
Use subagents or parallel agents per spec area, not per vague prompt.
Encode reusable flows as commands such as /implement-spec authentication.

# CLAUDE.md

Start by reading ./AGENTS.md.
In each folder, read the local README.md before making changes.
Use files under ./agents/ as source documents.
If implementing a feature, locate the relevant SPEC.md first.
Do not treat this file as the source of truth for product or architecture.

Source: Claude Code overview

Codex

Local, IDE, GitHub, cloud

Codex can work locally or in cloud environments and is effective when the repository already exposes constraints and setup clearly. SpecNative gives Codex a stable context surface across terminal, IDE, and delegated tasks.

Recommended pattern

Put repository rules in AGENTS.md and spec files, not only in task prompts.
For cloud tasks, ensure setup, commands, and validation live in repository files.
Delegate work by naming the spec or initiative folder, not by rewriting the entire project context.
Use Codex for implementation, refactoring, and review against explicit repository artifacts.

Implement the authentication initiative.

Read AGENTS.md first.
Then read agents/README.md, agents/ARCHITECTURE.md,
agents/CONVENTIONS.md, and agents/specs/authentication/SPEC.md.
Plan the work, implement it, run the documented validation commands,
and update DECISIONS.md if a persistent trade-off changes.

Sources: Codex cloud docs, Codex product overview

Implementation Flow

How a feature request becomes code

Define the capability

Write the behavior, scope, constraints, and acceptance criteria in a spec.

Read constraints

Load architecture, stack, conventions, and prior decisions before planning.

Generate tasks

Break the spec into implementation units that can be validated.

Implement and validate

Produce code, tests, and document updates that satisfy the spec.

Adoption

How to introduce SpecNative in a real codebase

Start small

Add AGENTS.md, a root README.md, and a single agents/SPEC.md for one active initiative.

Define durable truths

Move product intent, architecture, stack rules, commands, and conventions into repository files with clear ownership.

Route agents, do not brief them from scratch

Give the runtime a short entry instruction that tells it where to look, not a long project summary.

Expand only when needed

Introduce initiative folders, explicit task files, and workflow documents as project complexity increases.

Resources

Repository and references

README.md Engineering proposal in English README.es.md Spanish technical version Template-Project-Agents-AI Minimal repository template OpenCode Docs Agents, modes, permissions Claude Code Docs Overview, instructions, commands, hooks Codex Docs Cloud delegation and environment setup