repo-template
AGENTS.md0 starsChanged 17 days agoMIT-0View on GitHub
This repository is a template for projects that should carry their own shared instructions. Keep this file focused on agent-specific behavior. Put project overview, hosting, local development, workflow, and layout details in README.md and docs/. When adopting this template, replace bracketed placeholders with project-specific values and add focused docs only when the project needs them. When resuming work in this repository: Before running project commands or environment-dependent work: For the specific task:
- 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 repository2 other files it gives its agents.
- CLAUDE.mdCLAUDE.md
- git-cleanupSkill
The file
Show its rules and text
We split this AGENTS.md into the rules it gives an agent
27 rules. About 1 is common, 12 are distinctive, and 14 are very specific to this project.
≈1
Common · estimate
Many files like this have a rule of this kind.
≈12
Distinctive · estimate
This author's own choices. Worth a look.
14
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 5
When adopting this template, replace bracketed placeholders with project-specific values and add focused docs only when the project needs …
- Distinctive: line 9
When resuming work in this repository:
- Very specific: line 15
Read TEMPLATE_SOURCE.md if it exists, especially before changing shared setup or instruction files.
- Common: line 23
If the task depends on local configuration and required values are unset, ask for missing machine-specific values before assuming paths, …
- Very specific: line 27
Read the relevant documents in docs/ (see Docs Map below).
- Very specific: line 29
Run the appropriate make target when needed.
- Distinctive: line 33
Use paths relative to the repository root in documentation, comments, and handoffs.
- Distinctive: line 34
Do not include machine-local absolute paths in tracked files unless the user explicitly asks for a machine-specific note.
- Distinctive: line 36
Treat tracked source files as the source of truth.
- Very specific: line 37
Keep sensitive, large, received, raw, or machine-local files outside git.
- Very specific: line 38
Keep machine-specific settings in .env.local, and keep .env.local untracked.
- Very specific: line 39
Use Makefile targets for install, preview, build, test, lint, format, and cleanup tasks when targets exist.
- Very specific: line 40
When a durable command is missing, help add it to Makefile and document it in docs/local-development.md.
- Distinctive: line 41
When project structure or tooling choices are not settled, work with the human maintainer to clarify goals and use cases before choosing a …
- Distinctive: line 42
When relevant best practices may have changed, search online for current official documentation and reputable sources before recommending …
- Distinctive: line 44
Prefer small, coherent edits over broad rewrites.
- Very specific: line 45
Use soft wrap in Markdown and other prose files: one paragraph per source line.
- Distinctive: line 46
Do not invent facts, affiliations, announcements, citations, dates, or scientific claims.
- Distinctive: line 48
Update the relevant docs when you introduce a new durable convention.
- Distinctive: line 70
If a doc does not exist in the adopted project, infer the local pattern from nearby files and update the docs when the convention becomes …
- Very specific: line 74
Follow docs/agent-instructions.md when editing agent-facing instructions.
- Very specific: line 86
When work involves repeated manual steps, follow docs/automation-guide.md.
- Very specific: line 100
Before finishing a change, run the narrowest relevant make target documented in docs/local-development.md when practical.
- Very specific: line 104
When a convention is durable, repeated, or easy to get wrong, create a focused doc under docs/.
- Very specific: line 108
When this structure is adopted by another project, fill in TEMPLATE_SOURCE.md with the template repository, identifier, adoption date, …
- Distinctive: line 112
When handing work back to the user:
- Very specific: line 120
Do not assume context outside the repository unless it is documented in README.md, this file, docs/, or the user explicitly provides it.
≈ “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
AGENTS.md
This repository is a template for projects that should carry their own shared instructions. Keep this file focused on agent-specific behavior. Put project overview, hosting, local development, workflow, and layout details in README.md and docs/.
When adopting this template, replace bracketed placeholders with project-specific values and add focused docs only when the project needs them.
Start-of-Work Sequence
When resuming work in this repository:
Always:
- Read
README.md. - Read this file.
- Read
TEMPLATE_SOURCE.mdif it exists, especially before changing shared setup or instruction files.
Before running project commands or environment-dependent work:
- Read
docs/local-development.md. - Inspect
Makefileto learn the available targets and whether they depend on local configuration. - Inspect
.env.local.examplefor expected variables, and.env.localif it exists. Do not print secrets or copy private values into tracked files. - In a new git worktree (such as
.claude/worktrees/<name>), runmake worktree-setupto copy.env.localfrom the main worktree and create the_data/and_repos/links. See "Working in a Git Worktree" indocs/local-development.md. - If the task depends on local configuration and required values are unset, ask for missing machine-specific values before assuming paths, environment names, credentials, or data roots.
For the specific task:
- Read the relevant documents in
docs/(see Docs Map below). - Inspect target source files before editing them.
- Run the appropriate
maketarget when needed.
Primary Rules
- Use paths relative to the repository root in documentation, comments, and handoffs.
- Do not include machine-local absolute paths in tracked files unless the user explicitly asks for a machine-specific note.
- Do not reference a private repository from any other repository, and from a private repository name other repositories' threads in plain words instead of linking them. Before posting or pushing in a public repository, or posting text in a private repository that refers to another private repository, get a person's approval of the cleaned text. See "References Involving a Private Repository" in
docs/writing-guide.md. - Treat tracked source files as the source of truth. Do not commit generated artifacts unless the project documents them as published assets.
- Keep sensitive, large, received, raw, or machine-local files outside git. Use
_inbox/only for short-lived intake,_data/only as an ignored local link to the documented external root, and_repos/only for ignored local links to related repository clones. - Keep machine-specific settings in
.env.local, and keep.env.localuntracked. - Use
Makefiletargets for install, preview, build, test, lint, format, and cleanup tasks when targets exist. - When a durable command is missing, help add it to
Makefileand document it indocs/local-development.md. - When project structure or tooling choices are not settled, work with the human maintainer to clarify goals and use cases before choosing a convention.
- When relevant best practices may have changed, search online for current official documentation and reputable sources before recommending or adopting a toolchain, repository convention, or writing standard.
- Preserve existing content and naming conventions unless the user asks for a rewrite or migration.
- Prefer small, coherent edits over broad rewrites.
- Use soft wrap in Markdown and other prose files: one paragraph per source line. See
docs/writing-guide.md. - Do not invent facts, affiliations, announcements, citations, dates, or scientific claims.
- For current factual or scientific claims, verify against trusted sources before updating public-facing content.
- Update the relevant docs when you introduce a new durable convention.
Docs Map
docs/writing-guide.md: general prose, structure, links, paths, references involving a private repository, placeholders, and documentation checks.docs/issue-comments.md: issue bodies, progress comments, status words, next-action ownership, updating the issue when its pull request merges, replies to review comments, and posting images on issues and pull requests.docs/public-release.md: checklist for making a private repository public by publishing a history-free snapshot.docs/integrity.md: accurate claims and honest reports of work for every project, plus source hierarchy and citation checks for scientific or scholarly content.docs/testing-guide.md: test-driven development principles, test scenarios,make test, and minimum build checks.docs/privacy-guide.md: individual-level data protection, data minimization, and personal-information handling.docs/automation-guide.md: repeated work, scripts,maketargets, pipelines, and consistency improvements.docs/agent-instructions.md: maintaining clear, specific, non-conflictingAGENTS.md,CLAUDE.md, and nested instruction files.docs/manager-agent.md: the main agent as a manager of background subagents: delegating substantial editing, subagent prompts, deliverables and checks, outward-facing actions, and pausing and resuming with tasks files and handoffs under.claude/handoffs/.docs/template-adoption.md: recording the source template version and catching up with upstream template changes.docs/local-development.md:Makefiletargets, environment setup, preview commands, build commands, and validation checklist.docs/repository-layout.md: top-level files, path conventions, generated artifacts, and how to document project-specific layout.docs/related-repositories.md: ignored_repos/symlinks,.env.localvariables, and boundaries for related local clones.docs/external-data-layout.md: separating tracked source files from Box, Drive, raw-data, and other external storage.docs/inbox-triage.md: moving unsorted_inbox/files into tracked sources or ignored external storage.docs/project-specific-guidelines.md: how agents and maintainers should identify and create focused project-specific docs.docs/manuscript-evaluation.md: example workflow for evaluating manuscripts and comparing versions; adapt or remove for non-manuscript projects.
If a doc does not exist in the adopted project, infer the local pattern from nearby files and update the docs when the convention becomes stable.
Agent Instruction Hygiene
Follow docs/agent-instructions.md when editing agent-facing instructions. Keep top-level files (AGENTS.md, CLAUDE.md) concise, specific, and non-conflicting. Put durable procedures in docs/. Use nested AGENTS.md only when a subdirectory needs different instructions.
Writing and Sourcing
For prose and documentation changes, follow docs/writing-guide.md. For any factual claim, including reports of completed work, follow docs/integrity.md. For scientific, scholarly, clinical, biomedical, statistical, or data-driven claims, also follow its "Scientific and Scholarly Claims" section. Prefer primary literature, official organization pages, project-owned pages, and source documents already tracked by the repository. Use PubMed or PubMed Central for biomedical references when relevant.
Testing Discipline
For coding projects, follow docs/testing-guide.md. Identify expected behavior, positive controls, negative controls, and edge cases before changing behavior, and prefer adding or updating tests before implementation. For websites or rendered documentation, at minimum confirm make build succeeds.
Automation Discipline
When work involves repeated manual steps, follow docs/automation-guide.md. Notice repeated manual labor and propose scripts, make targets, tests, or pipelines that reduce variance. For repeated writing or review, propose reusable templates, rubrics, or checklists.
Privacy and Personal Data
When a project may touch individual-level data, personal information, correspondence, source files, or other non-public material, follow docs/privacy-guide.md, docs/external-data-layout.md, and docs/inbox-triage.md. Do not put real individual-level data in scripts, slides, examples, tests, fixtures, notebooks, or documentation without explicit human-maintainer approval. Prefer programmatic de-identification over manual agent inspection of raw records. Use role labels (such as "the student") in documentation when names are not necessary.
Environment Behavior
Use .env.local for machine-specific values; treat .env.local.example as documentation. Before running make targets that may depend on local paths, credentials, external data, or rendering tools, check whether required values are set and ask the user for missing values rather than guessing. Continue with task parts that do not depend on the local environment.
For new projects or unsettled tooling, first clarify what the project should produce, who will run it, what data and environments it depends on, and which compatibility constraints matter before choosing package managers, repository structure, or Makefile targets.
Validation
Before finishing a change, run the narrowest relevant make target documented in docs/local-development.md when practical. For Markdown-only docs, review changed files for links, paths, headings, and placeholders. If validation is skipped or fails, report that clearly and include the reason.
Project-Specific Docs
When a convention is durable, repeated, or easy to get wrong, create a focused doc under docs/. Do not keep narrow docs in this base template, but help create them when a real project needs them. See docs/project-specific-guidelines.md for examples and the adoption checklist.
Template Adoption
When this structure is adopted by another project, fill in TEMPLATE_SOURCE.md with the template repository, identifier, adoption date, copied files, and local adaptations. To catch up with a newer template version, follow docs/template-adoption.md.
Handoff Behavior
When handing work back to the user:
- Summarize the files changed.
- Mention validation performed.
- Name the evidence for each reported action, and report anything unconfirmed or skipped as such. See "Reporting What Was Done" in
docs/integrity.md. - Mention any remaining placeholders, missing local configuration, or follow-up checks.
- State whether you added an agent feedback note, following
agent-feedback/README.md.
Do not assume context outside the repository unless it is documented in README.md, this file, docs/, or the user explicitly provides it.
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.

