agentleFS
yk-tanigawayk-tanigawa/repo-template/AGENTS.md

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.

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
  1. Distinctive:

    When adopting this template, replace bracketed placeholders with project-specific values and add focused docs only when the project needs …

    line 5
  2. Distinctive:

    When resuming work in this repository:

    line 9
  3. Very specific:

    Read TEMPLATE_SOURCE.md if it exists, especially before changing shared setup or instruction files.

    line 15
  4. Common:

    If the task depends on local configuration and required values are unset, ask for missing machine-specific values before assuming paths, …

    line 23
  5. Very specific:

    Read the relevant documents in docs/ (see Docs Map below).

    line 27
  6. Very specific:

    Run the appropriate make target when needed.

    line 29
  7. Distinctive:

    Use paths relative to the repository root in documentation, comments, and handoffs.

    line 33
  8. Distinctive:

    Do not include machine-local absolute paths in tracked files unless the user explicitly asks for a machine-specific note.

    line 34
  9. Distinctive:

    Treat tracked source files as the source of truth.

    line 36
  10. Very specific:

    Keep sensitive, large, received, raw, or machine-local files outside git.

    line 37
  11. Very specific:

    Keep machine-specific settings in .env.local, and keep .env.local untracked.

    line 38
  12. Very specific:

    Use Makefile targets for install, preview, build, test, lint, format, and cleanup tasks when targets exist.

    line 39
  13. Very specific:

    When a durable command is missing, help add it to Makefile and document it in docs/local-development.md.

    line 40
  14. Distinctive:

    When project structure or tooling choices are not settled, work with the human maintainer to clarify goals and use cases before choosing a …

    line 41
  15. Distinctive:

    When relevant best practices may have changed, search online for current official documentation and reputable sources before recommending …

    line 42
  16. Distinctive:

    Prefer small, coherent edits over broad rewrites.

    line 44
  17. Very specific:

    Use soft wrap in Markdown and other prose files: one paragraph per source line.

    line 45
  18. Distinctive:

    Do not invent facts, affiliations, announcements, citations, dates, or scientific claims.

    line 46
  19. Distinctive:

    Update the relevant docs when you introduce a new durable convention.

    line 48
  20. Distinctive:

    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 …

    line 70
  21. Very specific:

    Follow docs/agent-instructions.md when editing agent-facing instructions.

    line 74
  22. Very specific:

    When work involves repeated manual steps, follow docs/automation-guide.md.

    line 86
  23. Very specific:

    Before finishing a change, run the narrowest relevant make target documented in docs/local-development.md when practical.

    line 100
  24. Very specific:

    When a convention is durable, repeated, or easy to get wrong, create a focused doc under docs/.

    line 104
  25. Very specific:

    When this structure is adopted by another project, fill in TEMPLATE_SOURCE.md with the template repository, identifier, adoption date, …

    line 108
  26. Distinctive:

    When handing work back to the user:

    line 112
  27. Very specific:

    Do not assume context outside the repository unless it is documented in README.md, this file, docs/, or the user explicitly provides it.

    line 120

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

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:

  1. Read README.md.
  2. Read this file.
  3. Read TEMPLATE_SOURCE.md if it exists, especially before changing shared setup or instruction files.

Before running project commands or environment-dependent work:

  1. Read docs/local-development.md.
  2. Inspect Makefile to learn the available targets and whether they depend on local configuration.
  3. Inspect .env.local.example for expected variables, and .env.local if it exists. Do not print secrets or copy private values into tracked files.
  4. In a new git worktree (such as .claude/worktrees/<name>), run make worktree-setup to copy .env.local from the main worktree and create the _data/ and _repos/ links. See "Working in a Git Worktree" in docs/local-development.md.
  5. 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:

  1. Read the relevant documents in docs/ (see Docs Map below).
  2. Inspect target source files before editing them.
  3. Run the appropriate make target 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.local untracked.
  • Use Makefile targets for install, preview, build, test, lint, format, and cleanup tasks when targets exist.
  • When a durable command is missing, help add it to Makefile and document it in docs/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, make targets, pipelines, and consistency improvements.
  • docs/agent-instructions.md: maintaining clear, specific, non-conflicting AGENTS.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: Makefile targets, 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.local variables, 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.

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.