Context files for better agent work

AI steering files for real projects.

A compact guide to the files that teach coding agents what your product is, how your codebase works, how your UI should feel, and what rules must shape every change.

Browse the catalog Use the checklist
repository root agent context layer
AGENTS.md A predictable operating manual for coding agents. DESIGN.md A design-system source of truth for AI-generated interface work. PRODUCT.md Product context that keeps implementation choices aligned with the business. TECH.md Technical stack and implementation constraints for future code changes. STRUCTURE.md A map of the codebase that helps agents put changes in the right place. VISION.md Longer-horizon direction that changes less often than product specs.

Core catalog

Start with the files agents are most likely to read and respect.

Each file should have a clear job. If two files repeat the same paragraph, one of them will drift. Keep the canonical facts in one place and point specialized tools back to that source.

AGENTS.md

AGENTS.md

A predictable operating manual for coding agents.

Best for: Build commands, tests, repo-specific rules, safety boundaries, and workflow expectations.

Should contain

  • setup, build, lint, test, and release commands
  • repository-specific coding conventions
  • review and safety rules agents must respect
  • where to find deeper docs when context is needed
AGENTS.md specOpenAI Codex guide

DESIGN.md

DESIGN.md

A design-system source of truth for AI-generated interface work.

Best for: Visual language, tokens, layout rules, component behavior, and product taste.

Should contain

  • machine-readable tokens for color, type, spacing, radius, and elevation
  • human-readable guidance for when and why to apply those tokens
  • component and interaction rules with concrete examples
  • anti-patterns that protect brand and usability
Google Stitch announcementDESIGN.md spec

PRODUCT.md

PRODUCT.md

Product context that keeps implementation choices aligned with the business.

Best for: Purpose, target users, key jobs, business model, positioning, and feature priorities.

Should contain

  • target users and their primary jobs
  • core workflows and success criteria
  • business objectives and constraints
  • product principles that should influence tradeoffs
Kiro steering docsKiro CLI steering

TECH.md

TECH.md

Technical stack and implementation constraints for future code changes.

Best for: Frameworks, libraries, tools, commands, runtime constraints, and dependency preferences.

Should contain

  • frameworks, languages, package managers, and runtime versions
  • approved libraries and discouraged alternatives
  • local development and CI commands
  • security, performance, and deploy constraints
Kiro steering docs

STRUCTURE.md

STRUCTURE.md

A map of the codebase that helps agents put changes in the right place.

Best for: Architecture, directory layout, import patterns, naming conventions, and ownership boundaries.

Should contain

  • major directories and what belongs in each
  • naming and import conventions
  • shared modules and extension points
  • examples of good local patterns to copy
Kiro steering docs

VISION.md

VISION.md

Longer-horizon direction that changes less often than product specs.

Best for: Taste, ambition, non-goals, operating philosophy, and the future shape of the project.

Should contain

  • why the project should exist in the long term
  • what the product should feel like when it is excellent
  • hard non-goals and tradeoffs
  • principles for deciding between plausible paths
PageFresh example PR

Related formats

Not every agent reads the same files.

Use generic files for durable knowledge, then add thin tool-specific wrappers only where the tool needs a special path or syntax.

.cursor/rules/*.mdc

Cursor Rules

Scoped instructions that Cursor can apply by file pattern or workflow.

Awesome Cursor Rules

CLAUDE.md, GEMINI.md, .github/copilot-instructions.md

Vendor Instruction Files

Tool-specific instruction files for agents that do not read the same generic context.

AGENTS.md examples

skills/*/SKILL.md

Agent Skills

Reusable workflows an agent can load only when a task requires specialized behavior.

Agent Skills overview

Writing checklist

Good steering files are short, specific, and grounded in the repo.

  1. Say what the file controls. Start with the scope and the intended reader.
  2. Prefer commands over vibes. Include exact install, test, lint, build, and deploy commands.
  3. Name the good examples. Point agents to files and modules that show the preferred pattern.
  4. Document constraints. Spell out security, data, accessibility, performance, and product boundaries.
  5. Keep canonical facts single-source. Link across files instead of duplicating long sections.
  6. Review after real agent work. Update the files when agents repeatedly ask the same question or make the same mistake.