agentleFS
osmlabosmlab/name-suggestion-index/AGENTS.md

name-suggestion-index

AGENTS.md893 starsChanged yesterdayBSD-3-ClauseView on GitHub

This file contains agent-specific guidance only. At session start, skim README.md and CONTRIBUTING.md for general project information. The knowledge/ folder holds notes for agents and people working on this project: work in progress, the backlog, completed work, decisions, lessons, and quirks. It's committed to git and public. At session start, read knowledge/current.md if it exists, and pull in the other files when they're relevant. Update them as you work. knowledge/README.md says what goes where, and how to prune. If this…

  • Where files are headingNew AGENTS.md files have more rules about keeping secrets out of the code, and fewer about code style.

    Of the AGENTS.md files we read, the 32,671 first seen in the last six months, against the older ones: the kind of rule that gained most share, and the kind that lost most. About files like this in general, not this one, and an estimate, since a kind is a pattern in the words.

  • In this repository8 other files it gives its agents.

The file

Show its rules and text

We split this AGENTS.md into the rules it gives an agent

15 rules. About 2 are common, 9 are distinctive, and 4 are very specific to this project.

  • ≈2

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈9

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 4

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    If this project has a design/ folder, it holds design docs for the larger systems: what each one owns, the decisions behind it, and where …

    line 17
  2. Distinctive:

    Before changing one of those systems, read its design doc: If your change alters the design, update the doc in the same change.

    line 18
  3. Distinctive:

    When you make a substantial change to a system that has no design doc yet, suggest starting one.

    line 19
  4. Very specific:

    Search tools usually skip gitignored files.

    line 25
  5. Very specific:

    Use the exact uppercase name.

    line 26
  6. Distinctive:

    Never copy anything from these files into committed files without asking.

    line 27
  7. Distinctive:

    Don't explain things the maintainer already knows (project context, how Git works, etc.).

    line 47
  8. Distinctive:

    If a PR does one thing, describe that one thing.

    line 48
  9. Distinctive:

    When the user proposes a solution, briefly evaluate whether a more elegant solution exists.

    line 53
  10. Distinctive:

    Keep it proportional: a heads-up is a sentence, not a paragraph.

    line 54
  11. Common:

    Before making any edit or commit, ask: could this write a secret in plaintext somewhere it shouldn't be?

    line 57
  12. Common:

    Never put tokens, keys, or passwords in plaintext in any unencrypted file.

    line 58
  13. Distinctive:

    Never remove comments: when modifying files unless:

    line 61
  14. Distinctive:

    If your change introduces a new lint warning, mention it.

    line 71
  15. Very specific:

    Avoid cat with heredoc or other terminal-based file writing.

    line 77

≈ “Common” is an estimate: at least 1 in 5 of the 41,581 AGENTS.md files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
AGENTS.md

Agent Context

This file contains agent-specific guidance only.

At session start, skim README.md and CONTRIBUTING.md for general project information.


Project knowledge

The knowledge/ folder holds notes for agents and people working on this project: work in progress, the backlog, completed work, decisions, lessons, and quirks. It's committed to git and public.

At session start, read knowledge/current.md if it exists, and pull in the other files when they're relevant. Update them as you work. knowledge/README.md says what goes where, and how to prune.

Design docs

If this project has a design/ folder, it holds design docs for the larger systems: what each one owns, the decisions behind it, and where it's heading. design/README.md lists them.

  • Before changing one of those systems, read its design doc. If your change alters the design, update the doc in the same change.
  • When you make a substantial change to a system that has no design doc yet, suggest starting one.

Private notes

Files named PRIVATE.* (e.g. PRIVATE.md, PRIVATE.json) are gitignored, and can be in any folder. They hold notes that shouldn't be public, such as personal context or unreleased plans.

  • At session start, read PRIVATE.md at the repo root if it exists.
  • Search tools usually skip gitignored files. Before working in a folder, check for a PRIVATE.* file there by opening the path directly, or list them all with find . -name 'PRIVATE.*' -not -path '*/node_modules/*'.
  • Use the exact uppercase name. On a case-sensitive file system, .gitignore won't match private.md.
  • Never copy anything from these files into committed files without asking.
  • Private isn't secret: no tokens, keys or passwords here either (see "Secrets hygiene" below).

Skills

This project has reusable agent skills in .claude/skills/: one folder per skill, each with a SKILL.md in the open Agent Skills format. Claude Code and VS Code Copilot both find them there and list them in the / menu (or equivalent). When a task matches an existing skill, prefer invoking it over improvising — the skills encode project-specific conventions.

Shared playbooks and lessons

agent-practices also keeps knowledge that applies across projects. It's written for agents, and isn't synced here, so fetch it:

  • Lessons, gotchas with the tools we use (Bun, TypeScript, packaging, git): https://raw.githubusercontent.com/rapideditor/agent-practices/main/lessons/README.md. At session start, read the index, then the lesson files for the tools this project uses. They're short, and they apply to everyday work, not just upgrades.
  • Playbooks for one-time upgrades (e.g. ESLint → oxlint, TypeScript 7): https://raw.githubusercontent.com/rapideditor/agent-practices/main/playbooks/README.md. Read the index before an upgrade, a tooling change or packaging work, then only the playbooks that apply.

Fetch the raw files with curl -fsSL (or gh api), so you get the exact text. A web-fetch tool that summarizes pages can drop the details that matter. This project's own conventions win where they differ. If you learn something that would help other projects, say so; /reflect can draft it for agent-practices.

General Guidelines

Communication style

  • Be concise. Maintainers review many contributions — get to the point.
  • Plain language over formal structure. A sentence or two beats a page of headings.
  • Don't explain things the maintainer already knows (project context, how Git works, etc.).
  • If a PR does one thing, describe that one thing.

Constructive Pushback

  • Don't just implement what's asked — briefly flag if you see a concern. The user values a 1-2 sentence heads-up over silent compliance.
  • This includes: unnecessary abstractions, deprecated patterns, simpler alternatives, or potential footguns.
  • When the user proposes a solution, briefly evaluate whether a more elegant solution exists.
  • Keep it proportional: a heads-up is a sentence, not a paragraph. Skip it entirely for trivial changes.

Secrets hygiene

  • Before making any edit or commit, ask: could this write a secret in plaintext somewhere it shouldn't be?
  • Never put tokens, keys, or passwords in plaintext in any unencrypted file.

Comments

  • Never remove comments when modifying files unless:
    • The comment applies to code being removed
    • The meaning of the code has changed
    • Specifically asked to remove them
  • Comments contain valuable domain knowledge — preserve them.
  • Also don't add unsolicited comments or docstrings to code you're modifying. Only add explanatory comments when the user asks, when documenting a non-obvious decision (magic numbers, workarounds), or when the code is genuinely confusing without them.

Lint warnings

  • Never circumvent lint warnings by renaming, reformatting, or otherwise disguising the triggering code to silence a rule.
  • Lint warnings are intentional project health signals — they should remain visible.
  • If your change introduces a new lint warning, mention it; don't silently suppress it.

File Operations

  • Edit files using the structured file-editing operations exposed by your host environment — e.g. the create_file / replace_string_in_file / multi_replace_string_in_file tools in VS Code Copilot, the equivalent Edit / Write tools in Claude Code, Cursor's edit tools, an MCP filesystem server, or whatever your runtime offers. These show changes in a reviewable diff and (where applicable) require exact-match context, which prevents silent damage that regex-based tools can cause.
  • For bulk/repetitive edits across multiple files, prefer a multi-edit operation (e.g. multi_replace_string_in_file) over many separate calls when your environment supports it.
  • Do not mutate files via shell stream-editing tools like sed, perl -i, awk -i, or inline python -c / node -e scripts. Greedy regexes (especially around whitespace and line boundaries) can collapse or corrupt code in ways that are hard to spot without a full re-read. If an edit feels too repetitive for the structured edit tools, that's a signal to slow down, not to reach for a script.
  • Avoid cat with heredoc or other terminal-based file writing.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.