perberperber/leafwiki/AGENTS.md

leafwiki

AGENTS.md1.2k starsChanged 17 days agoMITView on GitHub

Instructions for AI coding agents (Claude Code, Codex, Cursor, Copilot, Gemini, …) in this repository. Humans start at CONTRIBUTING.md; the rules are the same. If AGENTS.local.md exists in the repository root, read it next. It holds maintainer-local instructions, is never committed, and wins where it conflicts with this file. LeafWiki is a self-hosted wiki: Markdown files on disk are the source of truth, SQLite indexes are derived and rebuildable, one binary for Linux, Windows, macOS and Raspberry Pi. Backend: layered…

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 31,774 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 repository6 other files it gives its agents.
- CLAUDE.mdCLAUDE.md
- developSkill
- docs-reviewSkill
- runSkill
- tidy-testsSkill
- worktree-cleanupSkill

The file

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

4 rules. About 0 are common, 2 are distinctive, and 2 are very specific to this project.

≈0
Common · estimate
Many files like this have a rule of this kind.
≈2
Distinctive · estimate
This author's own choices. Worth a look.
2
Very specific
Tied to their project's names, files or tools. Probably skip.

Common
Distinctive
Very specific

Very specific:
If AGENTS.local.md exists in the repository root, read it next.
line 6
Distinctive:
Read before changing code — docs/development/: rules (the short list, same for people and agents), conventions (the reference behind them), …
line 16
Distinctive:
Read them before changing code.
line 44
Very specific:
Committing locally is fine: when the history is clean: one logical change per commit, Conventional Commits (type(scope): description), …
line 52

≈ “Common” is an estimate: at least 1 in 5 of the 40,246 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

Instructions for AI coding agents (Claude Code, Codex, Cursor, Copilot, Gemini, …) in this repository. Humans start at CONTRIBUTING.md; the rules are the same.

If AGENTS.local.md exists in the repository root, read it next. It holds maintainer-local instructions, is never committed, and wins where it conflicts with this file.

The project

LeafWiki is a self-hosted wiki: Markdown files on disk are the source of truth, SQLite indexes are derived and rebuildable, one binary for Linux, Windows, macOS and Raspberry Pi. Backend: layered Go (cmd/leafwiki → internal/wiki composition root → slices → internal/core/*). Frontend: React SPA in ui/leafwiki-ui with feature-local Zustand stores.

Read before changing code — docs/development/: rules (the short list, same for people and agents), conventions (the reference behind them), source map, architecture, processes, ADRs.

Commands

What	Command	Where
Local subset of the PR checks: verify, lint, deadcode, test, cross, ui-check (not 386 tests, govulncheck, Trivy, install-script test, e2e lint, E2E, Dev Container build)	`make ci`	repo root
Backend tests / lint	`make test` / `make lint` (golangci-lint at the version in `.golangci-lint-version`)	repo root
Repository checks (private references, toolchain versions)	`make verify`	repo root
Windows/macOS build check	`make cross` (build + vet for windows/amd64, darwin/arm64)	repo root
Frontend install + lint + format check + tests + build	`make ui-check`	repo root
Frontend typecheck + build	`npm run build` (not `npx tsc --noEmit`, it checks nothing)	`ui/leafwiki-ui`
Frontend tests / lint / format	`npm test` / `npm run lint -- --max-warnings=0` / `npm run format`	`ui/leafwiki-ui`
E2E	`make run-e2e`; lint/format in `e2e`	repo root
Local dev	`make dev` (both, Ctrl-C stops both), or backend: `go run . --jwt-secret=dev --admin-password=devpassword --public-access=true --allow-insecure=true` in `cmd/leafwiki`; frontend: `npm run dev`

A fresh worktree has no node_modules: run make setup (npm ci --ignore-scripts in ui/leafwiki-ui and e2e) first; make doctor checks the Go and Node versions. Toolchain versions have one source each: Go in go.mod's toolchain line, Node in .nvmrc; make verify checks that the Dockerfiles and mise.toml match.

Rules

The rules live in docs/development/rules.md, nowhere else. Read them before changing code; don't restate them in prompts, skills or roles, link there. Much of it is enforced in CI (import boundaries, ESLint XSS guard, i18n key parity, golangci-lint, Prettier, Windows/macOS cross build, private references); a red check is a real finding. Commit subjects are checked too (make verify-commits BASE=origin/main), as information: messy contributor PRs get squash-merged.

Commits and pull requests

Committing locally is fine when the history is clean: one logical change per commit, Conventional Commits (type(scope): description), refactoring, behaviour change and test: tidy in separate commits, formatters run, tests green. Never commit secrets, generated files or local overlays.
Pushing, opening PRs and commenting on GitHub need the person's explicit OK.
PR size and scope: rules and conventions; process in CONTRIBUTING.md and AI-assisted contributions.

Workflow and roles

Changes run through independent roles, scaled by tier (details in the develop skill): trivial (typo, rename, docs) → implement + CI; normal (change inside one slice) → implement + tester + architecture-reviewer + reviewer; feature (new feature, extension point, API or format change) → all roles with a plan gate; + security for anything touching rendering, uploads, served files, auth, routes or paths.

Roles in .claude/agents/ (plain Markdown prompts): planner, architecture-reviewer, implementer, reviewer, tester, security-reviewer. Each runs with a fresh context; the checking roles see only the plan and the diff. Without subagent support, run each role in its own session with its file as instructions.

Skills

Runbooks in .claude/skills/<name>/SKILL.md: develop (the workflow above), tidy-tests (restructure a package's tests with proof nothing was lost), run (start backend + frontend), docs-review (docs vs. code), worktree-cleanup.

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.

Check your setup, free