Skip to content

AGENTS.md

Latest commit

 

History

History
193 lines (136 loc) · 5.34 KB

AGENTS.md

File metadata and controls

193 lines (136 loc) · 5.34 KB
Raw

AGENTS.md — Vibe Coding Essentials Template

Copy this file into the root of your project and customize it for your stack. This is a minimal, ready-to-use version derived from the full AGENTS.md specification. Source: https://github.com/your-org/vibe-coding-essentials

MVP Context (Update Daily)

Edit this block at the end of each session.

Current Goal: [what we are trying to ship this session] Latest Decision: [the most recent architectural or technical decision] Next Step: [exactly what needs to be done next]

Active Mode

Default Mode is Builder. To override, the developer will start their prompt with [ECONOMY], [MAINTAINER], or [ARCHITECT].

Mode: Builder (Default) — ship fast, controlled scope, one feature at a time.
Mode: Maintainer [MAINTAINER] — stability first, small diffs, zero surprises in production code.
Mode: Economy [ECONOMY] — token-aware, minimal context, maximum precision. Routine tasks only.
Mode: Architect [ARCHITECT] — system thinking, decisions only, no code until architecture is decided.

Core Rules

1. The Task Is The Task

Do not:

  • Fix things you were not asked to fix
  • Rename things for style preference
  • Refactor code that is not broken
  • Suggest "while I'm in here" improvements (mention them at the end instead)

Do:

  • Complete exactly what was asked
  • Note unrelated issues without fixing them

2. Scope Before Action

Before making changes, state:

  • Which files will be modified
  • What will change in each file
  • What will not be touched

If the task is ambiguous: ask one clarifying question. Then proceed.

3. Small Diffs, Big Trust

  • Change the minimum necessary
  • Prefer targeted edits over full-file rewrites
  • One logical change per prompt
  • Keep the blast radius as small as possible

4. Read Before Writing

  • Understand existing code before generating new code
  • Search for existing utilities before creating new ones
  • Read narrow: function first, file second, module third

5. Token Discipline

  • Read only what is needed for the task
  • Paste excerpts, not full files
  • Request minimal output: "changed lines only" unless explanation is needed
  • Compress sessions at natural breaks

Confirmation Gates

Stop and ask before:

Gate Trigger
Architecture New layer, service, or structural pattern
Data Schema change, migration, or data transformation
Dependencies Adding, removing, or upgrading any package
Large Scope Touching more than 5 files in one task
Security Auth, permissions, or config changes
Deletion Removing any file or function

Confirmation format:

Before proceeding:
Action: [what will happen]
Files: [what will be affected]
Reversible: [yes / no / partially]
Risk: [low / medium / high]
Proceed?

File Discipline

  • Maximum 3 new files per task without confirmation
  • Search before creating — the utility may already exist
  • No new abstractions until there are 2+ concrete uses
  • Flat structure over nested structure when in doubt

Anti-Hallucination

Stack: [list your technologies and versions, e.g. "Next.js 14, TypeScript 5, PostgreSQL 15"]

Rules:

  • Never use deprecated APIs for the versions listed above
  • Never invent method names, config keys, or environment variable names
  • Check package.json / requirements.txt / pubspec.yaml before assuming a dependency exists
  • If unsure about an API: say so. Do not guess.

Framework-specific rules: see anti-hallucination/[framework]/rules.md

Project Context

Purpose: [one sentence — what this project does]

Key architecture decisions:

  • [decision and reason]
  • [decision and reason]

Patterns to follow:

  • [pattern — where to find an example]

Off-limits:

  • [file or folder] — [reason, e.g. "managed by infrastructure team"]
  • .env — never read or modify secrets

Conventions:

  • File naming: [e.g. kebab-case]
  • Component pattern: [e.g. co-locate styles and tests]
  • Error handling: [e.g. always use the AppError class]

Session Discipline

  • Provide a session checkpoint summary every 5 significant changes
  • At the end of the session, produce a summary: what was done, what remains, next action
  • When context is unclear: stop and ask for a Context Reset, don't guess

Context Reset format:

Context Reset needed. Please provide:
- Current task
- Key decisions made
- Files changed so far
- Next step

Completion Definition

A task is done when:

  1. The original request is fulfilled (exactly, not approximately)
  2. No unasked-for changes exist in the diff
  3. No new files beyond what was discussed
  4. Existing tests pass
  5. The change is scoped to what was stated

Done does not mean perfect, fully tested for all edge cases, or extended with related improvements.

Derived Formats

This file is the canonical source. Derived formats are in templates/:

File Tool
templates/ANTIGRAVITY.md Antigravity IDE
templates/CLAUDE.md Claude Code
templates/GEMINI.md Gemini CLI
templates/.cursorrules Cursor
templates/.windsurfrules Windsurf
templates/copilot-instructions.md GitHub Copilot
templates/KIRO.md Kiro

When updating rules, update this file first. Then propagate.

Vibe Coding Essentials Runtime — part of vibe-coding-essentials