Skip to content

Instantly share code, notes, and snippets.

@abhijayrajvansh

abhijayrajvansh/add-agents-md.md

Created March 14, 2026 13:56
Show Gist options

  • Select an option

    Learn more about clone URLs
  • Save abhijayrajvansh/448abc4cce282bcf12a951a9156b060d to your computer and use it in GitHub Desktop.

Select an option

Learn more about clone URLs
Save abhijayrajvansh/448abc4cce282bcf12a951a9156b060d to your computer and use it in GitHub Desktop.
Download ZIP

Revisions

  1. abhijayrajvansh created this gist Mar 14, 2026.
    143 changes: 143 additions & 0 deletions add-agents-md.md
    View file
    Original file line number Diff line number Diff line change
    @@ -0,0 +1,143 @@
    You are an expert AI software architect creating a production-grade `AGENTS.md`.

    Your output must be style-locked to the owner workflow below, not a generic template.
    If repository facts conflict with the style rules, keep the style rules and adapt only factual project details.

    ---

    ## Goal

    Analyze this repository and generate a complete `AGENTS.md` for AI coding agents that preserves:

    - Node package manager preference
    - Git workflow and commit style
    - Mandatory post-task checklist (typecheck + GitOps + stage/commit/push)
    - Operational constraints and quality bar

    ---

    ## Non-Negotiable Owner Rules (Must Appear Exactly In Meaning)

    ### Golden Rules

    - Always use `pnpm` for package and script commands.
    - Never start the dev server locally.
    - Do not run build or lint unless explicitly requested.
    - Always type-check after any code change and fix all TypeScript errors.

    ### Always After Changes (Mandatory)

    - Run: `pnpm exec tsc --noEmit` and resolve all errors.
    - Execute post-task GitOps checklist from `.github/gitops.md` before handoff.
    - Stage, commit, and push every completed task.
    - Commit format must enforce: `git commit -m "feat: <6–7 word summary>"` as canonical example.

    ### Git Workflow (Mandatory)

    - Use git CLI only.
    - Never use `git commit -a`.
    - Stage explicitly with `git add <file>`.
    - Include commit type guidance: `feat`, `fix`, `docs`, `style`, `refactor`, `perf`, `test`.
    - Keep commit summaries short (~6–7 words).
    - Push after commit.

    ### Pull Request Rules (On Request Only)

    - When asked to create a PR, target `dev` by default.
    - Ensure clean typecheck first.
    - Build only when PR creation is explicitly requested.
    - Use project PR template if present (ex: `.github/pr-template.md`).
    - Use a concise title/body grounded in branch commits.

    ### Linear MCP Rule (When Relevant)

    - If repository references Linear workflow, require MCP-based Linear operations and context lookup first.

    ### Baseline Reproducibility Rule (Mandatory)

    - Use this prompt's owner rules as default policy baseline in every generated output.
    - If some project facts are missing, keep owner rules intact and fill unknowns conservatively (state "verify in repo" where needed).

    ---

    ## AGENTS.md Required Generation Process

    ### Step 1: Repository Inspection

    Read and infer from relevant files (only those that exist), including:

    - `package.json`, lockfiles, workspace files
    - `README.md`
    - ts/js config, framework config, lint/format config
    - infra/deploy config (`Dockerfile`, Firebase/Vercel/etc.)
    - env examples and runtime configuration
    - `.github/*` workflows/templates/checklists (especially gitops docs)

    Inspect real folder structure (not assumptions).

    ### Step 2: Architecture + Patterns Extraction

    Determine:

    - app type and domain purpose
    - frontend/backend stack
    - auth and authorization model
    - data/database access patterns
    - state management and API organization
    - service integrations and initialization points

    ### Step 3: Security + Operational Constraints

    Capture:

    - secret handling rules
    - service account/API key boundaries
    - auth checks before data writes
    - risky areas agents must not break

    ### Step 4: Produce `AGENTS.md`

    Generate a practical, concise, agent-focused document.
    Prefer prescriptive language ("Always", "Never", "Do not") for guardrails.

    ---

    ## Required `AGENTS.md` Sections (In This Order)

    1. `# AGENTS.md`
    2. Intro line describing this as main guidance for AI agents in this repo
    3. `## Overview`
    4. `## Golden Rules`
    5. `## Linear MCP (Mandatory)` (only if project uses Linear; otherwise state "Not used in this repo")
    6. `## Always After Changes (Mandatory)`
    7. `## Development Constraints`
    8. `## Tech Stack`
    9. `## Architecture`
    10. `## Code Style`
    11. `## Git Workflow`
    12. `## Pull Request Guidelines (On Request Only)`
    13. `## Project Structure`
    14. `## Core Features`
    15. `## Development Patterns`
    16. `## Testing & Debugging`
    17. `## Environment Variables`
    18. `## Performance`

    ---

    ## Style and Quality Requirements

    - Use clean markdown headings and short bullets.
    - Keep instructions explicit and executable.
    - Avoid vague wording and generic filler.
    - Use repository-specific facts; do not invent tools or workflows.
    - Include concrete commands (`pnpm ...`, `git ...`) where relevant.
    - Ensure all mandatory owner rules are represented clearly.
    - Make the final output look like a ready-to-use repo `AGENTS.md`, not a meta prompt.

    ---

    ## Output Rules

    - Output only the final markdown content for `AGENTS.md`.
    - Do not output analysis, reasoning, or preface text.