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

Revisions

  1. pixeline revised this gist Dec 19, 2025. 1 changed file with 11 additions and 3 deletions.
    14 changes: 11 additions & 3 deletions agentsmd.md
    View file
    Original file line number Diff line number Diff line change
    @@ -2,9 +2,7 @@
    Cursor command that generates a useful agents.md in the active project.
    This file should be placed in the `~/.cursor/commands` folder.
    More info on Cursor Commands: https://cursor.com/docs/agent/chat/commands
    As anything AI, don't take the output for granted and carefully review it.
    -->

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

    @@ -17,20 +15,27 @@ Produce a short, concrete, machine-oriented guide that lets an AI agent be produ
    - Every rule must be actionable (commands, conventions, constraints).
    - Prefer bullets, code blocks, and explicit rules.
    - Assume the agent will follow this file strictly.
    - Test every command to make sure it works before adding the command in the AGENTS.md file
    - Prefer commands that are fast + non-destructive.
    - Verify commands before listing them:
    - If safe/fast: run them.
    - If slow/interactive/destructive: do NOT run; instead verify they exist in config/scripts and mark as "(unverified)" in AGENTS.md.
    - The file must be placed at the root level and named exactly "AGENTS.md" (note the capital letter casing).
    - Do not include secrets, credentials, tokens, license keys, or internal-only URLs. Do not copy login/passwords from docs.
    - When referencing a URL, wrap it in backticks.

    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.
    - If this is a monorepo or has multiple entrypoints, prefer adding nested AGENTS.md files in subprojects *only when necessary*; otherwise document subproject-specific commands with explicit `cd path` prefixes.

    ## 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).
    - If nested AGENTS.md files exist/are needed, state precedence: the closest AGENTS.md to the edited file wins.

    ### Agent Role
    - Define the agent persona (e.g. “experienced backend dev for this stack”).
    @@ -43,12 +48,14 @@ You MUST base the content on the actual repository context:
    - lint / format
    - test (prefer scoped or fast commands)
    - Use fenced code blocks only.
    - Every command must be copy/pastable and include required working directory context (use `cd path && ...` when not repo-root).

    ### Conventions & Patterns
    - Naming conventions
    - File/folder structure rules
    - Architectural patterns actually used in the repo
    - Preferred libraries or approaches (with brief examples if helpful)
    - State explicit search constraints (e.g. exclude `vendor/`, `node_modules/`).

    ### Dos and Don’ts
    - Explicit behavioral rules (e.g. “Do not add new dependencies without approval”)
    @@ -58,6 +65,7 @@ You MUST base the content on the actual repository context:
    - 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).
    - Explicitly list any directories that must never be edited (e.g. generated code, vendored deps, framework core).

    ### Git & PR Rules
    - Branching model
  2. pixeline revised this gist Dec 19, 2025. 1 changed file with 7 additions and 0 deletions.
    7 changes: 7 additions & 0 deletions agentsmd.md
    View file
    Original file line number Diff line number Diff line change
    @@ -1,3 +1,10 @@
    <!--
    Cursor command that generates a useful agents.md in the active project.
    This file should be placed in the `~/.cursor/commands` folder.
    More info on Cursor Commands: https://cursor.com/docs/agent/chat/commands
    As anything AI, don't take the output for granted and carefully review it.
    -->

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

  3. pixeline revised this gist Dec 19, 2025. 1 changed file with 4 additions and 2 deletions.
    6 changes: 4 additions & 2 deletions agentsmd.md
    View file
    Original file line number Diff line number Diff line change
    @@ -1,5 +1,5 @@
    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.
    Your task is to create an accurate 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.
    @@ -10,6 +10,8 @@ Produce a short, concrete, machine-oriented guide that lets an AI agent be produ
    - Every rule must be actionable (commands, conventions, constraints).
    - Prefer bullets, code blocks, and explicit rules.
    - Assume the agent will follow this file strictly.
    - Test every command to make sure it works before adding the command in the AGENTS.md file
    - The file must be placed at the root level and named exactly "AGENTS.md" (note the capital letter casing).

    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.).
    @@ -52,7 +54,7 @@ You MUST base the content on the actual repository context:

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

    ### Additional rules
  4. pixeline revised this gist Dec 19, 2025. 1 changed file with 1 addition and 3 deletions.
    4 changes: 1 addition & 3 deletions agentsmd.md
    View file
    Original file line number Diff line number Diff line change
    @@ -1,5 +1,3 @@
    Generate an excellent AGENTS.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.

    @@ -54,7 +52,7 @@ You MUST base the content on the actual repository context:

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

    ### Additional rules
  5. pixeline revised this gist Dec 19, 2025. No changes.
  6. pixeline revised this gist Dec 19, 2025. No changes.
  7. pixeline created this gist Dec 19, 2025.
    67 changes: 67 additions & 0 deletions agentsmd.md
    View file
    Original file line number Diff line number Diff line change
    @@ -0,0 +1,67 @@
    Generate an excellent AGENTS.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
    - 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.