Skip to content

Instantly share code, notes, and snippets.

@pixeline

pixeline/agentsmd.md

Last active December 19, 2025 11:43
Show Gist options

  • Select an option

    Learn more about clone URLs
  • Save pixeline/d07867718d7294a18f5588625370665e to your computer and use it in GitHub Desktop.

Select an option

Learn more about clone URLs
Save pixeline/d07867718d7294a18f5588625370665e to your computer and use it in GitHub Desktop.
Download ZIP
Cursor command that generates a useful AGENTS.md in the active project. This file should be placed in the `~/.cursor/commands` folder.
Raw
agentsmd.md

You are an experienced senior engineer joining this repository today. Your task is to create an AGENTS.md file that will be used by AI coding agents working in this repo.

Goal: Produce a short, concrete, machine-oriented guide that lets an AI agent be productive in minutes without guessing.

Hard requirements

  • Max ~150 lines. Shorter is better if nothing useful is lost.
  • No narrative prose, no marketing language, no theory.
  • Every rule must be actionable (commands, conventions, constraints).
  • Prefer bullets, code blocks, and explicit rules.
  • Assume the agent will follow this file strictly.

You MUST base the content on the actual repository context:

  • Infer the tech stack from config files (package.json, composer.json, pyproject.toml, go.mod, etc.).
  • Infer test tools, linters, formatters, and build systems from what is present.
  • Do not invent tools, scripts, or commands that do not exist.
  • If something is unclear or missing, state it explicitly as a constraint.

Required sections (use these headings exactly)

Overview & Scope

  • One-paragraph description of what this project is.
  • Specify which folders/subprojects this file applies to (important for monorepos).

Agent Role

  • Define the agent persona (e.g. “experienced backend dev for this stack”).
  • Explicitly state what the agent is allowed to do and not do.

Build, Test & Validation Commands

  • Exact one-line commands for:
  • install / setup
  • build (if applicable)
  • lint / format
  • test (prefer scoped or fast commands)
  • Use fenced code blocks only.

Conventions & Patterns

  • Naming conventions
  • File/folder structure rules
  • Architectural patterns actually used in the repo
  • Preferred libraries or approaches (with brief examples if helpful)

Dos and Don’ts

  • Explicit behavioral rules (e.g. “Do not add new dependencies without approval”)
  • Call out common mistakes to avoid in THIS repo.

Safety & Guardrails

  • What is off-limits (prod data, secrets, infra, migrations, large rewrites, etc.).
  • What tasks are safe to automate.
  • Constraints on command execution (avoid slow or global operations).

Git & PR Rules

  • Branching model
  • Commit message format. If none is specified, use the Conventional Commits standard.
  • PR expectations (tests required, description style, etc.)

Additional rules

  • Do NOT duplicate the README; link to it if needed.
  • If multiple AGENTS.md files should exist (root + subfolders), state that clearly.
  • Assume this file must stay accurate; avoid speculative or aspirational content.

Output

  • Return only valid Markdown for AGENTS.md.
  • No explanations, no preamble, no commentary outside the file.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment