Repository‑aware prompt that generates or enhances AGENTS.md for precise, reliable AI agent execution without guesswork.

agentsmd-authoring-prompt.md

AGENTS.md Authoring Prompt

You are a Principal Software Architect & Documentation Lead AI. Your mission is to create or enhance the AGENTS.md file at the repository root so that AI coding assistants can follow it without guesswork. First analyze the repository. At minimum, examine config/build files, scripts, directory layout, tests, linters/formatters, CI workflows, recent commits, and docs/templates. If AGENTS.md exists, validate it against the repository's reality and these guidelines; reuse the existing section structure; prefer in-place edits; only restructure when evidence shows gaps, conflicts, or drift; keep changes minimal and style-aligned. If it does not exist, author a clear, concise, and actionable AGENTS.md from scratch. Verify every command and path exists and runs here; prefer file-scoped/targeted checks and concrete relative paths. Write the content to ./AGENTS.md at the repository root; ensure the file contains only the AGENTS.md Markdown itself, without explanatory comments, boilerplate, or meta notes.

Core Principles

Apply these principles throughout the authoring process:

1. Single Source of Truth

   • When versions, commands, or settings live in dedicated files (package.json, Makefile, pyproject.toml, build configs, CI workflows), reference those paths instead of duplicating values
   • Avoid copying content from README or other docs; reference or summarize instead
   • Use format: "See path/to/file for [type]" or "Refer to file:section"
   • Inline only when: (1) no authoritative source exists, or (2) a brief example significantly aids understanding
   • Consider trade-offs:
     • Reference when: values may change (versions, URLs, commands)
     • Inline when: explaining complex patterns, showing project-specific conventions

2. Specificity Over Generality

   • ❌ "React project" → ✅ "React + TypeScript + Vite + Tailwind (see package.json for versions)"
   • Be specific about what tools exist; reference canonical files for versions
   • When details aren't specified anywhere, state what exists without inventing

3. Examples Over Explanations

   • One real code snippet beats three paragraphs of description
   • Include ✅ Good / ❌ Bad examples for non-obvious or project-specific patterns

4. Minimal Changes

   • When editing existing AGENTS.md: prefer in-place edits within current headings
   • Keep diffs focused and small; add/remove/reorder sections only with clear evidence
   • Follow the repository's prevailing style

5. Evidence-Based

   • Base all content on evidence from this repository
   • No invented rules, placeholders, or assumptions
   • Validate every command and path before including

6. Style Consistency

   • Follow existing formatting and structure
   • Match dominant comment language/style
   • Keep changes aligned with repository conventions

Objectives

• Provide a clear, concise, well-structured guide for agents.
• Keep it ecosystem-agnostic: include only tools, commands, and patterns that actually exist here.
• Prefer file-scoped checks and concrete paths; avoid unactionable prose.

Before You Write (derive facts from the repo)

• Tooling and language: detect languages, frameworks, build systems, dependency managers, formatter/linter/test tools, and CI from config or build files.
• Commands: collect real install/run/build/test/type-check/lint/format commands from scripts or build files.
• Structure: map key directories and files (source, tests, assets, configuration, data/API clients, styles or tokens if present).
• Docs: start with README(.md), then CONTRIBUTING.md, root .md (e.g., CODE_OF_CONDUCT.md, SECURITY.md), and docs/ for goals, setup, constraints.
• Conventions: infer naming, import order, file layout, component/class patterns, state/data access.
• Detect dominant comment style/language.
• Commits and PRs: review the latest 20-30 commits and consult CONTRIBUTING.md, commitlint/config files, PR templates, and any templates/linters to infer commit style and PR expectations.
• Anti-patterns: list deprecated patterns, legacy files, or examples to avoid if they materially exist.
• Inventory: list files and directories at the root to form a quick map before deeper reads.
• Iterative deep dive: read a small set of high-signal files first (about ~10 files), then pick the next files based on what you discover.

Document Rules for AGENTS.md

• Title the document "Repository Guidelines".
• Provide only examples that are guaranteed to work here (commands, relative paths, naming patterns).
• Formatting: use standard Markdown (headings, short paragraphs, bullet lists); keep bullets single-level when possible; deepen only when needed.
• Scope and precedence: ignore environment defaults or org/parent guides not present in this repository.
• Repository type: if this is not a software codebase, adapt sections to emphasize directory overview, key files, and usage; omit build/test/command sections that don't apply.

Sections to Include (adapt as needed; omit if not applicable)

1. Build, Test, and Development Commands

• Put executable commands early—agents reference these often.
• Reference Strategy (apply "Single Source of Truth"):
  • For stable commands: reference the source file
    • Example: "Build: see Makefile targets" or "Tests: see .github/workflows/test.yml"
  • For complex workflows: include a brief example + reference
    • Example: "Run targeted test: npm test -- path/to/test.js (see package.json for all test scripts)"
  • Inline when it aids understanding without creating maintenance burden
    • Example: showing a multi-step setup sequence unique to this project
• List key commands to install/run/build/test locally.
• Emphasize file-scoped/targeted variants first; include 1-2 real examples only when necessary for clarity.
• Note prerequisites or ordering if relevant (e.g., run install before build).

2. Project Structure and Module Organization

• Briefly state what the project does.
• Show where source, tests, assets, config, and data/API clients live (real paths), and where CI workflows reside (e.g., .github/workflows/*).

3. Coding Style and Naming Conventions

• Base rules: indentation, language-specific preferences, import style, naming patterns, preferred split/size.
• Include ✅ Good / ❌ Bad code examples for non-obvious or project-specific patterns.
• Comments: match the dominant comment language/style observed.
• Conflicts: if styles conflict, follow the prevalent majority; if unclear, use minimal conventional defaults.

4. Testing Guidelines

• Describe: frameworks, locations, naming, how to run targeted tests.
• Practice: if this repo usually adds tests for new features/bug fixes, keep that practice.
• Fallback: if unclear, add minimal targeted tests for externally observable behavior/regressions; avoid broad rewrites.
• Coverage: mention targets only if configured in this repo.

5. Commit and Pull Request Guidelines

• Summarize practice from the latest 20-30 commits/templates/linters.
• If a clear convention exists, reference it (e.g., CONTRIBUTING.md, commitlint config) or show one brief example.
• Otherwise use neutral guidance (small focused diffs, imperative messages, link issues when relevant, pass all checks configured here).
• Include screenshots or short recordings when UI/UX is affected.

6. Boundaries

Use three-tier format:

• ✅ Always do: Read or list files; run file-scoped type/lint/format/test; create small focused patches.
• ⚠️ Ask first: Adding dependencies; deleting or renaming files; modifying configuration; pushing branches; full builds or end-to-end suites.
• 🚫 Never do: Production-impacting destructive operations; commit secrets or sensitive data.

Optional (include only if evidence exists)

• Security and Configuration Tips (for secrets and sensitive settings).
• Architecture Overview (one short paragraph, high-signal only).
• Agent-Specific Instructions (reuse typed clients or design tokens rather than re-implementing).
• API Documentation (where docs live; typed clients/schemas).
• Design System References (tokens/components if they exist).

Quality Gates Before Finalizing

Verify compliance with Core Principles:

• Applicable areas covered: Include sections that apply to this repo; omit those without supporting evidence
• Specificity: Tech stack names tools concretely; versions reference canonical files
• Examples: Non-obvious or project-specific style rules have Good/Bad code snippets
• Evidence-Based: Every command and path validated; no placeholders or invented rules
• Single Source of Truth: Referenced canonical files (package.json, Makefile, CI configs) instead of copying
• Minimal Changes: Kept diffs focused; preserved existing structure unless clear gap exists
• Style Consistency: Matched repository conventions and formatting
• Functional: Tested at least one command end-to-end to verify it runs

Begin execution now: analyze the repository and write ./AGENTS.md at the repository root as specified above.