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.
- rust-best-practicesSkill
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
- Distinctive: line 10
Prefer the professional, durable solution over a quick patch.
- Distinctive: line 11
Keep changes scoped to the requested behavior and avoid unrelated refactors.
- Distinctive: line 12
Read the relevant code before editing.
- Distinctive: line 15
Do not leave dead code, fake stubs, unused helpers, TODO-heavy placeholders, or partial implementations that pretend to be complete.
- Distinctive: line 48
Do not put scanning, rule, scoring, generation, or report-building logic in the CLI crate.
- Distinctive: line 50
Do not make report rendering inspect the filesystem or run scan logic.
- Distinctive: line 51
Do not make config code print, prompt, scan, or render reports.
- Distinctive: line 52
Keep library crates free of terminal styling, prompts, and process exits.
- Distinctive: line 53
Add abstractions only when they remove real duplication or clarify ownership.
- Distinctive: line 54
Prefer explicit domain types and typed errors in library crates.
- Very specific: line 57
Use #![forbid(unsafe_code)] in every Rust crate.
- Very specific: line 58
Do not add unsafe.
- Very specific: line 59
Do not use .unwrap() or .expect() in production code unless the invariant is obvious and the reason is documented.
- Distinctive: line 61
Do not panic for normal user input, filesystem state, invalid config, or CLI mistakes.
- Very specific: line 63
Use Path and PathBuf; never string-concatenate filesystem paths.
- Very specific: line 64
Keep modules focused. Do not create broad utils.rs dumping grounds.
- Distinctive: line 65
Avoid large files and unrelated helper functions.
- Distinctive: line 66
Keep public APIs small, typed, and stable enough for the CLI, future TUI, and release automation to reuse.
- Distinctive: line 68
Do not add heavy dependencies, network clients, async runtimes, AI SDKs, or parser frameworks without a clear product need.
- Distinctive: line 72
Add or update tests for every behavior change.
- Distinctive: line 73
Prefer engine fixture regression tests for scan, rule, score, and generation behavior.
- Distinctive: line 75
When adding an agent surface such as skills, prompts, custom agents, hooks, MCP config, or tool-specific instruction files, add real …
- Distinctive: line 79
Use CLI integration tests for command behavior, stdout/stderr contracts, exit codes, config precedence, and no-write guarantees.
- Distinctive: line 81
Use report tests for JSON shape and pretty output grouping.
- Distinctive: line 83
Do not weaken or delete tests to make a change pass.
- Distinctive: line 87
Do not add telemetry.
- Distinctive: line 88
Do not call AI APIs.
- Distinctive: line 89
Do not perform network access during scans.
- Very specific: line 90
Do not read, print, or copy secret values from .env files.
- Very specific: line 91
Treat .env, credentials, tokens, private keys, and local machine paths as sensitive.
- Distinctive: line 96
Keep Windows, macOS, and Linux install paths documented and tested where practical.
- Very specific: line 98
Do not break install.ps1, install.sh, or scripts/install-local.ps1 behavior when changing release artifacts.
- Distinctive: line 100
Keep upgrade network access isolated to lifecycle commands.
- Very specific: line 102
Keep uninstall confirmation-gated.
- Very specific: line 108
Run cargo fmt --all -- --check after Rust changes.
- Very specific: line 109
Run cargo clippy --workspace --all-targets -- -D warnings after Rust changes.
- Very specific: line 111
Run cargo test --workspace after behavior, test, config, report, CLI, or fixture changes.
- Very specific: line 113
Run cargo build --workspace --release after CLI, dependency, release, or installer changes.
- Distinctive: line 117
Verify the installed or built CLI manually when changing install, release, or command behavior.
≈ “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.
Files
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.
clapfor CLI parsing.serde,serde_json, andtomlfor serialization.ignorefor repository walking.directoriesfor 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, andinstall.ps1contain 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
PathandPathBuf; never string-concatenate filesystem paths. - Keep modules focused. Do not create broad
utils.rsdumping 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
.envfiles. - 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, orscripts/install-local.ps1behavior 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 -- --checkafter Rust changes. - Run
cargo clippy --workspace --all-targets -- -D warningsafter Rust changes. - Run
cargo test --workspaceafter behavior, test, config, report, CLI, or fixture changes. - Run
cargo build --workspace --releaseafter 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.
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
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.

