AGENTS.md Contract

Each generated template now ships with an AGENTS.md file— a focused operating contract for AI assistants (Cursor, Copilot Chat, PR bots) powered by agents.md.

Purpose

Separate human docs from AI guidance

Humans read README + docs/*. AI assistants read AGENTS.md for rules, guardrails, and execution steps.

Guardrails

Reduce hallucinations + unsafe changes

Explicit refusal cases, escalation triggers, and validation reminders keep AI changes scoped + safe.

Workflow

Reinforce expected execution flow

Encourages read-before-write, plan-before-apply, and explicit assumption surfacing.

Generated Example (Web Server Template)

A trimmed example of the AGENTS.md shipped with the web-server starter template.

# AGENTS.md – AI Interaction & Execution Guide (Human contributors: see CONTRIBUTING.md & docs/)

This file is intentionally scoped **only** for AI assistants (Cursor, Copilot Chat, PR automation bots).
Humans: read CONTRIBUTING.md and the documents under docs/.

## 1. Authoritative References (Never Reproduce Content Here)

| Topic | Source of Truth |
|-------|-----------------|
| Project architecture | docs/PROJECT_STRUCTURE.md |
| API route patterns | docs/API_GUIDELINES.md |
| Settings & env vars | docs/CONFIGURATION.md |
| Database / ORM usage | docs/DATABASE.md |
| Testing strategy | docs/TESTING.md |
| Deployment notes | docs/DEPLOYMENT.md |

## 2. Operating Principles (AI Perspective)

- Documentation-first
- Reuse-before-build
- Keep V code fmt/vet clean
- Deterministic, incremental changes
- Explicit assumption logging

## 3. AI Execution Protocol (V Feature Work)

When asked to add/modify API behavior:
1. Locate the relevant V module (top-level feature dirs)
2. Read related docs/* referenced above
3. Prefer extending existing handlers/modules over new entrypoints
4. Show proposed file tree + diff plan BEFORE writing code
5. After code: list follow-up validation steps (v fmt, v vet, v test)

## 4. Guardrails (Must Enforce)

- Do NOT fabricate file paths, settings keys, or package versions
- Do NOT invent VPM module versions or import paths
- Do NOT nest modules under src/features/ (V imports break)
- ALWAYS flag new v.mod dependencies for human confirmation
- ALWAYS surface GC / concurrency tradeoffs when changing systems code

## 5. Module Change Checklist

- Public API documented; keep modules top-level
- Entrypoint wires the new module
- Config via documented env samples when extensions provide them
- v test coverage added or deferred with reason
- docs/ updated when architecture changes

## 6. When the AI Should Ask or Refuse

Ask for clarification if: feature scope unclear, conflicting patterns, missing target module.
Refuse if: asked to bypass validation, skip v vet, or invent undocumented VPM deps.

## 7. Post-Change Assistant Report

Return a bullet summary:
- Files touched (concise)
- New dependencies (if any)
- v fmt / v vet / v test status
- Suggested manual QA steps
- Deferred items (tests, docs)

---
Maintained automatically by create-vlang-app web-server template provisioning.
Humans: stop reading—go to CONTRIBUTING.md + docs/.

Customizing Your AGENTS.md

Adapting for your team

Feel free to extend sections (Guardrails, Protocol, Refusal Conditions) but avoid duplicating rich procedural docs—link to existing sources instead.

Add domain-specific escalation triggers (security, data, billing)
Reference internal design system docs instead of re-stating variants
Include CI scripts or task runners (e.g. v test ., v fmt . && v vet .) if not obvious
Keep tone imperative and concise—optimize for machine parsing + embedding

Explore More

Back to Docs View Templates

# AGENTS.md – AI Interaction & Execution Guide (Human contributors: see CONTRIBUTING.md & docs/) This file is intentionally scoped **only** for AI assistants (Cursor, Copilot Chat, PR automation bots). Humans: read CONTRIBUTING.md and the documents under docs/. ## 1. Authoritative References (Never Reproduce Content Here) | Topic | Source of Truth | |-------|-----------------| | Project architecture | docs/PROJECT_STRUCTURE.md | | API route patterns | docs/API_GUIDELINES.md | | Settings & env vars | docs/CONFIGURATION.md | | Database / ORM usage | docs/DATABASE.md | | Testing strategy | docs/TESTING.md | | Deployment notes | docs/DEPLOYMENT.md | ## 2. Operating Principles (AI Perspective) - Documentation-first - Reuse-before-build - Keep V code fmt/vet clean - Deterministic, incremental changes - Explicit assumption logging ## 3. AI Execution Protocol (V Feature Work) When asked to add/modify API behavior: 1. Locate the relevant V module (top-level feature dirs) 2. Read related docs/* referenced above 3. Prefer extending existing handlers/modules over new entrypoints 4. Show proposed file tree + diff plan BEFORE writing code 5. After code: list follow-up validation steps (v fmt, v vet, v test) ## 4. Guardrails (Must Enforce) - Do NOT fabricate file paths, settings keys, or package versions - Do NOT invent VPM module versions or import paths - Do NOT nest modules under src/features/ (V imports break) - ALWAYS flag new v.mod dependencies for human confirmation - ALWAYS surface GC / concurrency tradeoffs when changing systems code ## 5. Module Change Checklist - Public API documented; keep modules top-level - Entrypoint wires the new module - Config via documented env samples when extensions provide them - v test coverage added or deferred with reason - docs/ updated when architecture changes ## 6. When the AI Should Ask or Refuse Ask for clarification if: feature scope unclear, conflicting patterns, missing target module. Refuse if: asked to bypass validation, skip v vet, or invent undocumented VPM deps. ## 7. Post-Change Assistant Report Return a bullet summary: - Files touched (concise) - New dependencies (if any) - v fmt / v vet / v test status - Suggested manual QA steps - Deferred items (tests, docs) --- Maintained automatically by create-vlang-app web-server template provisioning. Humans: stop reading—go to CONTRIBUTING.md + docs/.