Skip to content

Instantly share code, notes, and snippets.

@milllan

milllan/refactor my AGENTS.md

Created January 19, 2026 13:03
Show Gist options

  • Select an option

    Learn more about clone URLs
  • Save milllan/6e354f0e22a0433a63d200fc47f02ea0 to your computer and use it in GitHub Desktop.

Select an option

Learn more about clone URLs
Save milllan/6e354f0e22a0433a63d200fc47f02ea0 to your computer and use it in GitHub Desktop.
Download ZIP
Raw
refactor my AGENTS.md

I want you to refactor my AGENTS.md file to follow progressive disclosure principles.

Follow these steps:

  1. Find contradictions: Identify any instructions that conflict with each other. For each contradiction, ask me which version I want to keep.

  2. Identify the essentials: Extract only what belongs in the root AGENTS.md:

    • One-sentence project description
    • Package manager (if not npm)
    • Non-standard build/typecheck commands
    • Anything truly relevant to every single task

  3. Group the rest: Organize remaining instructions into logical categories (e.g., TypeScript conventions, testing patterns, API design, Git workflow). For each group, create a separate markdown file.

  4. Create the file structure: Output:

    • A minimal root AGENTS.md with markdown links to the separate files
    • Each separate file with its relevant instructions
    • A suggested docs/ folder structure

  5. Flag for deletion: Identify any instructions that are:

    • Redundant (the agent already knows this)
    • Too vague to be actionable
    • Overly obvious (like "write clean code")
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment