From bffb2fbbfd68f7ffd38db9d18f3ca66766762926 Mon Sep 17 00:00:00 2001 From: sneak Date: Sun, 4 Oct 2026 04:51:08 +0000 Subject: [PATCH] Keep agent guidance in one root AGENTS.md (closes #31) The canonical REPO_POLICIES.md now says that guidance for coding agents lives in one AGENTS.md at the repository root, including anything an agent should remember between sessions, and is never committed under a file or directory named after one agent tool or split into separate memory files. This retires the in-repo memory rule that older vendored copies still carry. AGENTS.md is added to the list of files allowed in the root, which would otherwise contradict the new rule. Both checklists carry the matching item. Model: opus-5-5 --- TODO.md | 6 ++++++ prompts/EXISTING_REPO_CHECKLIST.md | 4 ++++ prompts/NEW_REPO_CHECKLIST.md | 3 +++ prompts/REPO_POLICIES.md | 14 ++++++++++---- 4 files changed, 23 insertions(+), 4 deletions(-) diff --git a/TODO.md b/TODO.md index ad8770e..0015bad 100644 --- a/TODO.md +++ b/TODO.md @@ -21,6 +21,12 @@ fmt-check, and commit. # Completed Steps +- 2026-10-04: `REPO_POLICIES.md` now states that guidance for coding agents + lives in one `AGENTS.md` at the repository root, never under a file or + directory named after one agent tool and never in separate memory files (issue + 31). This retires the rule, still present in older vendored copies, that kept + agent memory as committed files under `.claude/memory/`. `AGENTS.md` joins the + list of files allowed in the root, and both checklists say so. - 2026-10-04: The Makefile examples in the Go styleguide and the HTTP server conventions now fall back to `dev` when `git describe` prints nothing (outside a git checkout, or where git is missing or refuses the checkout), instead of diff --git a/prompts/EXISTING_REPO_CHECKLIST.md b/prompts/EXISTING_REPO_CHECKLIST.md index 21b00fa..316cc29 100644 --- a/prompts/EXISTING_REPO_CHECKLIST.md +++ b/prompts/EXISTING_REPO_CHECKLIST.md @@ -24,6 +24,10 @@ with your task. - [ ] `LICENSE` file exists and matches the README - [ ] `REPO_POLICIES.md` exists and version date is current — fetch from `https://git.eeqj.de/sneak/prompts/raw/branch/main/prompts/REPO_POLICIES.md` +- [ ] Guidance for coding agents, if the repo has any, is one `AGENTS.md` at the + root — never a file or directory named after one agent tool, such as + `CLAUDE.md` or `.claude/`, and never separate memory files. Move what any + such committed file says into `AGENTS.md` and delete it. - [ ] `.gitignore` is comprehensive (OS, editor, agent scratch, language artifacts, secrets) — fetch from `https://git.eeqj.de/sneak/prompts/raw/branch/main/.gitignore` if missing. diff --git a/prompts/NEW_REPO_CHECKLIST.md b/prompts/NEW_REPO_CHECKLIST.md index ecdd444..c229df2 100644 --- a/prompts/NEW_REPO_CHECKLIST.md +++ b/prompts/NEW_REPO_CHECKLIST.md @@ -54,6 +54,9 @@ Template files can be fetched from: - [ ] `LICENSE` file matching the chosen license - [ ] `REPO_POLICIES.md` — fetch from `https://git.eeqj.de/sneak/prompts/raw/branch/main/prompts/REPO_POLICIES.md` +- [ ] Guidance for coding agents, if the repo has any, is one `AGENTS.md` at the + root — never a file or directory named after one agent tool, such as + `CLAUDE.md` or `.claude/`, and never separate memory files - [ ] `Dockerfile` and `.dockerignore` — fetch `.dockerignore` from `https://git.eeqj.de/sneak/prompts/raw/branch/main/.dockerignore` - Extend `.dockerignore` with the repo's own host-built artifacts, giving diff --git a/prompts/REPO_POLICIES.md b/prompts/REPO_POLICIES.md index 3f35e47..0d352b5 100644 --- a/prompts/REPO_POLICIES.md +++ b/prompts/REPO_POLICIES.md @@ -605,10 +605,10 @@ style conventions are in separate documents: settings. - Avoid putting files in the repo root unless necessary. Root should contain - only project-level config files (`README.md`, `Makefile`, `Dockerfile`, - `LICENSE`, `.gitignore`, `.editorconfig`, `REPO_POLICIES.md`, and - language-specific config). Everything else goes in a subdirectory. Canonical - subdirectory names: + only project-level config files (`README.md`, `AGENTS.md`, `Makefile`, + `Dockerfile`, `LICENSE`, `.gitignore`, `.editorconfig`, `REPO_POLICIES.md`, + and language-specific config). Everything else goes in a subdirectory. + Canonical subdirectory names: - `bin/` — executable scripts and tools - `cmd/` — Go command entrypoints; thin only: one `main.go` per binary whose body is a single call into `internal/` or `pkg/`, no project logic in @@ -639,3 +639,9 @@ style conventions are in separate documents: - Go: `go.mod`, `go.sum`, `.golangci.yml` - JS: `package.json`, `yarn.lock`, `.prettierrc`, `.prettierignore` - Python: `pyproject.toml` + +- Guidance for coding agents lives in one `AGENTS.md` at the repository root, + including anything an agent should remember about the repo from one session to + the next. It is never committed under a file or directory named after one + agent tool, such as `CLAUDE.md` or `.claude/`, and never split into separate + memory files.