agentleFS
youssefszyoussefsz/agentdoctor/AGENTS.md

agentdoctor

AGENTS.md9 starsChanged 5 months agoMITView on GitHub

  • Reads credentials
  • 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 repositoryOne other file it gives its agents.

The file

Show its rules and text

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

39 rules. About 0 are common, 26 are distinctive, and 13 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈26

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 13

    Very specific

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

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    Prefer the professional, durable solution over a quick patch.

    line 10
  2. Distinctive:

    Keep changes scoped to the requested behavior and avoid unrelated refactors.

    line 11
  3. Distinctive:

    Read the relevant code before editing.

    line 12
  4. Distinctive:

    Do not leave dead code, fake stubs, unused helpers, TODO-heavy placeholders, or partial implementations that pretend to be complete.

    line 15
  5. Distinctive:

    Do not put scanning, rule, scoring, generation, or report-building logic in the CLI crate.

    line 48
  6. Distinctive:

    Do not make report rendering inspect the filesystem or run scan logic.

    line 50
  7. Distinctive:

    Do not make config code print, prompt, scan, or render reports.

    line 51
  8. Distinctive:

    Keep library crates free of terminal styling, prompts, and process exits.

    line 52
  9. Distinctive:

    Add abstractions only when they remove real duplication or clarify ownership.

    line 53
  10. Distinctive:

    Prefer explicit domain types and typed errors in library crates.

    line 54
  11. Very specific:

    Use #![forbid(unsafe_code)] in every Rust crate.

    line 57
  12. Very specific:

    Do not add unsafe.

    line 58
  13. Very specific:

    Do not use .unwrap() or .expect() in production code unless the invariant is obvious and the reason is documented.

    line 59
  14. Distinctive:

    Do not panic for normal user input, filesystem state, invalid config, or CLI mistakes.

    line 61
  15. Very specific:

    Use Path and PathBuf; never string-concatenate filesystem paths.

    line 63
  16. Very specific:

    Keep modules focused. Do not create broad utils.rs dumping grounds.

    line 64
  17. Distinctive:

    Avoid large files and unrelated helper functions.

    line 65
  18. Distinctive:

    Keep public APIs small, typed, and stable enough for the CLI, future TUI, and release automation to reuse.

    line 66
  19. Distinctive:

    Do not add heavy dependencies, network clients, async runtimes, AI SDKs, or parser frameworks without a clear product need.

    line 68
  20. Distinctive:

    Add or update tests for every behavior change.

    line 72
  21. Distinctive:

    Prefer engine fixture regression tests for scan, rule, score, and generation behavior.

    line 73
  22. Distinctive:

    When adding an agent surface such as skills, prompts, custom agents, hooks, MCP config, or tool-specific instruction files, add real …

    line 75
  23. Distinctive:

    Use CLI integration tests for command behavior, stdout/stderr contracts, exit codes, config precedence, and no-write guarantees.

    line 79
  24. Distinctive:

    Use report tests for JSON shape and pretty output grouping.

    line 81
  25. Distinctive:

    Do not weaken or delete tests to make a change pass.

    line 83
  26. Distinctive:

    Do not add telemetry.

    line 87
  27. Distinctive:

    Do not call AI APIs.

    line 88
  28. Distinctive:

    Do not perform network access during scans.

    line 89
  29. Very specific:

    Do not read, print, or copy secret values from .env files.

    line 90
  30. Very specific:

    Treat .env, credentials, tokens, private keys, and local machine paths as sensitive.

    line 91
  31. Distinctive:

    Keep Windows, macOS, and Linux install paths documented and tested where practical.

    line 96
  32. Very specific:

    Do not break install.ps1, install.sh, or scripts/install-local.ps1 behavior when changing release artifacts.

    line 98
  33. Distinctive:

    Keep upgrade network access isolated to lifecycle commands.

    line 100
  34. Very specific:

    Keep uninstall confirmation-gated.

    line 102
  35. Very specific:

    Run cargo fmt --all -- --check after Rust changes.

    line 108
  36. Very specific:

    Run cargo clippy --workspace --all-targets -- -D warnings after Rust changes.

    line 109
  37. Very specific:

    Run cargo test --workspace after behavior, test, config, report, CLI, or fixture changes.

    line 111
  38. Very specific:

    Run cargo build --workspace --release after CLI, dependency, release, or installer changes.

    line 113
  39. Distinctive:

    Verify the installed or built CLI manually when changing install, release, or command behavior.

    line 117

≈ “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 Instructions

Project overview

AgentDoctor is a Rust 2024 CLI-first workspace that audits repositories for AI coding agent readiness. The project must stay clean, deterministic, cross-platform, and maintainable. Treat this as production-quality developer tooling, not a prototype.

Operating principles

  • Prefer the professional, durable solution over a quick patch.
  • Keep changes scoped to the requested behavior and avoid unrelated refactors.
  • Read the relevant code before editing; do not guess when the repository can answer the question.
  • Plan first for ambiguous or multi-file work, then implement.
  • Do not leave dead code, fake stubs, unused helpers, TODO-heavy placeholders, or partial implementations that pretend to be complete.
  • Make behavior verifiable with tests or a clear command-level check.
  • Preserve deterministic output for generated files and reports.

Stack

  • Rust 2024 workspace.
  • clap for CLI parsing.
  • serde, serde_json, and toml for serialization.
  • ignore for repository walking.
  • directories for platform-native config paths.
  • assert_cmd, tempfile, and fixture repos for tests.

Commands

  • format: cargo fmt --all
  • format check: cargo fmt --all -- --check
  • lint: cargo clippy --workspace --all-targets -- -D warnings
  • test: cargo test --workspace
  • build: cargo build --workspace --release

Project structure

  • crates/agentdoctor-engine/ owns scanning, rule execution, scoring, and deterministic init generation.
  • crates/agentdoctor-config/ owns global and project configuration loading, saving, and precedence.
  • crates/agentdoctor-report/ renders already-built reports only.
  • crates/agentdoctor-cli/ owns CLI parsing, prompts, terminal output, exit codes, and user-facing errors.
  • fixtures/ contains regression repositories used by tests.
  • scripts/, install.sh, and install.ps1 contain installer helpers.
  • .github/workflows/ contains CI and release automation.

Architecture boundaries

  • Do not put scanning, rule, scoring, generation, or report-building logic in the CLI crate.
  • Do not make report rendering inspect the filesystem or run scan logic.
  • Do not make config code print, prompt, scan, or render reports.
  • Keep library crates free of terminal styling, prompts, and process exits.
  • Add abstractions only when they remove real duplication or clarify ownership.
  • Prefer explicit domain types and typed errors in library crates.

Code quality

  • Use #![forbid(unsafe_code)] in every Rust crate.
  • Do not add unsafe.
  • Do not use .unwrap() or .expect() in production code unless the invariant is obvious and the reason is documented.
  • Do not panic for normal user input, filesystem state, invalid config, or CLI mistakes.
  • Use Path and PathBuf; never string-concatenate filesystem paths.
  • Keep modules focused. Do not create broad utils.rs dumping grounds.
  • Avoid large files and unrelated helper functions.
  • Keep public APIs small, typed, and stable enough for the CLI, future TUI, and release automation to reuse.
  • Do not add heavy dependencies, network clients, async runtimes, AI SDKs, or parser frameworks without a clear product need.

Testing standards

  • Add or update tests for every behavior change.
  • Prefer engine fixture regression tests for scan, rule, score, and generation behavior.
  • When adding an agent surface such as skills, prompts, custom agents, hooks, MCP config, or tool-specific instruction files, add real filesystem-based tests that prove discovery, rule findings, score evidence, and JSON-safe output behavior.
  • Use CLI integration tests for command behavior, stdout/stderr contracts, exit codes, config precedence, and no-write guarantees.
  • Use report tests for JSON shape and pretty output grouping.
  • Golden output tests are appropriate for deterministic generated files.
  • Do not weaken or delete tests to make a change pass. Fix the implementation or update expectations only when the behavior intentionally changed.

Security and privacy

  • Do not add telemetry.
  • Do not call AI APIs.
  • Do not perform network access during scans.
  • Do not read, print, or copy secret values from .env files.
  • Treat .env, credentials, tokens, private keys, and local machine paths as sensitive.
  • Generated content must not include secrets or machine-local private values.

Installer and release rules

  • Keep Windows, macOS, and Linux install paths documented and tested where practical.
  • Do not break install.ps1, install.sh, or scripts/install-local.ps1 behavior when changing release artifacts.
  • Keep upgrade network access isolated to lifecycle commands. Scans must remain offline and deterministic.
  • Keep uninstall confirmation-gated; non-interactive uninstall must require an explicit --yes.
  • Release archives must include the binary, README, and LICENSE.
  • CI must stay strict: fmt, clippy with -D warnings, tests, and release build.

Before finishing

  • Run cargo fmt --all -- --check after Rust changes.
  • Run cargo clippy --workspace --all-targets -- -D warnings after Rust changes.
  • Run cargo test --workspace after behavior, test, config, report, CLI, or fixture changes.
  • Run cargo build --workspace --release after CLI, dependency, release, or installer changes.
  • For docs-only changes, run the smallest relevant validation and state what was not run.
  • Verify the installed or built CLI manually when changing install, release, or command behavior.
  • Final responses must clearly state what changed and which checks were run.

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.