AGENTS.md · HonoAGENTS.md and CLAUDE.md examples for Hono
Of 93 actively developed open-source products built with Hono, 74 (80%) keep instruction files for coding agents: AGENTS.md in 69, CLAUDE.md in 49. The typical file is 1,207 words, and most cover commands to build, run and test (79%) and pointers to other docs (70%).
Real files to read
From the best-known open-source Hono products whose file is a real one (not a pointer to another), 200 to 4,000 words, covering at least three of the usual topics and naming Hono. Each opens on GitHub.
| Project | File | Stars | Words | Covers |
|---|---|---|---|---|
| labring/FastGPT | AGENTS.md | 29,797 | 491 | CommandsTestingDoc pointers |
| kriasoft/react-starter-kit | AGENTS.md | 23,687 | 845 | CommandsTestingDoc pointersStructureCode style |
| open-pencil/open-pencil | AGENTS.md | 8,866 | 2,356 | CommandsTestingDoc pointersCode styleGit |
| latitude-dev/latitude-llm | AGENTS.md | 4,719 | 1,892 | CommandsTestingDoc pointersCode style |
| SonicJs-Org/sonicjs | AGENTS.md | 1,749 | 1,346 | CommandsTestingDoc pointersStructureCode styleGit |
| theopenco/llmgateway | AGENTS.md | 1,684 | 1,672 | CommandsTestingDoc pointersStructureCode styleGit |
| fredrikburmester/streamystats | CLAUDE.md | 826 | 2,130 | CommandsStructureCode styleGit |
| loglayer/loglayer | AGENTS.md | 548 | 2,059 | CommandsTestingDoc pointersStructureCode style |
| deadlock-mod-manager/deadlock-mod-manager | AGENTS.md | 480 | 751 | CommandsDoc pointersCode style |
| akash-network/console | AGENTS.md | 264 | 1,027 | CommandsTestingDoc pointersStructureCode styleGit |
| Cloudflare-Studio/ask-bonk | AGENTS.md | 263 | 1,294 | CommandsTestingStructureCode style |
What Hono projects put in them
Share of the 73 files that cover each topic, against all 641 files we read.
How they talk to the agent: 81% say “never” or “do not” somewhere (all files: 80%), 25% shout a rule in capitals like IMPORTANT or MUST (24%), and 19% tell it to ask before some changes (20%).
The tools they name
Package managerspnpm (25 files), bun (20 files), npm (12 files)
Tests and lintersVitest (22), Playwright (14), ESLint (13), Biome (11), Prettier (7), pytest (3)
Named more than in files generallyVitest (22), PostgreSQL (18), Bun (15), Cloudflare (13), Cursor (13), Biome (11), Zod (11), Turborepo (9)
What they tell the agent
Instructions that recur across files, in our words; open one for the Hono projects whose file says it.
About Hono
Used as the lightweight HTTP framework for backend API services, often on Cloudflare Workers or Bun.11 files
About Vitest
Co-locate Vitest test files next to the source they test.3 files
While iterating, run a single test file or filtered scope rather than the whole suite.2 files
Use Vitest for unit tests and Playwright for end-to-end or browser tests.1 files
Run Vitest non-interactively with run or --run, never in watch mode, especially in automation.1 files
About PostgreSQL
Named as the project's main relational database, often alongside Redis.3 files
Pair PostgreSQL with Drizzle as the ORM and schema layer.4 files
Use the pgvector extension for embeddings and vector search inside PostgreSQL.3 files
Keep code portable across PostgreSQL and the other supported engines such as SQLite or MySQL.2 files
About Bun
Use Bun for installs and scripts (bun install, bun run, bunx); don't use npm, pnpm, or yarn.2 files
Tests run on Bun's built-in runner (bun:test), with caveats about module mocks, timeouts, and per-package runs.4 files
Repo is a Bun workspaces monorepo, often orchestrated with Turborepo.3 files
Use the pinned Bun version from the repo.3 files
About Cloudflare
Named as the runtime and host: the backend runs as Cloudflare Workers, often with Hono.9 files
Use Cloudflare R2 as the object storage for uploads, media and release artifacts.1 files
Use Cloudflare D1 as the SQLite database.3 files
Deploy to Cloudflare with the Wrangler CLI or a Wrangler-based CI workflow.2 files
About Cursor
The file is written for any AI coding agent, listing Cursor next to Claude Code, Copilot, and Codex.5 files
Cursor Cloud agent VMs have their own environment setup notes, secrets, and caveats documented separately.2 files
Cursor-specific rules live under a dot-cursor directory.1 files
Cursor is named as an MCP client, alongside Claude Desktop, that can connect to the project's server.1 files
About Biome
Code style such as indentation, quotes, and semicolons is dictated by the Biome config, so follow it.2 files
Run Biome through package scripts such as lint, format, check, or fix, optionally with auto-fix.3 files
Biome is used through the Ultracite preset, which sets the lint and format rules.1 files
Biome handles both linting and formatting, replacing ESLint and Prettier, so don't add those.1 files
About Zod
Validate all external or untrusted input, such as requests and payloads, with Zod schemas at the boundary.2 files
Keep Zod schemas in one dedicated shared location rather than inline in pages or routers.2 files
Forms pair React Hook Form with Zod for validation.3 files
About Turborepo
Turborepo orchestrates build, test, and lint tasks across a pnpm or Bun workspace monorepo.4 files
Task pipeline and cache settings live in turbo.json.2 files
Turborepo behavior varies by version, so read the docs bundled in the installed turbo package before changing config.2 files
A starting AGENTS.md for Hono
The sections these files cover most, the package manager and checks Hono projects name most, and the stack Hono makers' products chose most often. Fill in the <placeholders>.
# AGENTS.md <What this product does and who it is for, in a sentence or two.> ## Stack - Backend Framework: Hono ## Commands - Install: `pnpm install` - Run locally: `<command>` - Test: `pnpm exec vitest run` - End-to-end tests: `pnpm exec playwright test` - Lint: `pnpm exec eslint .` ## Testing Run `pnpm exec vitest run` and `pnpm exec playwright test` before calling a change done, and add a test with each fix or feature. ## Project structure - `<folder>/`: <what lives there> - More in <docs/…> ## Conventions - <Naming, patterns and style the code does not show> - Commits and pull requests: <your rules> ## Boundaries - Ask before: <changes you want to approve first> - Never: <files or actions that are off-limits> <!-- Started from https://howmakersbuild.com/agents-md/hono — point CLAUDE.md here with a line: @AGENTS.md -->
- pnpm: named in 25 of 73 instruction files from open-source projects built with Hono.
- Vitest: named in 22 of 73 instruction files from open-source projects built with Hono.
- Playwright: named in 14 of 73 instruction files from open-source projects built with Hono.
- ESLint: named in 13 of 73 instruction files from open-source projects built with Hono.
Questions
What should an AGENTS.md for a Hono project include?
In 73 files from open-source Hono products: commands to build, run and test (79%), pointers to other docs (70%), testing (68%), project structure (58%), code style (52%), git, commits and pull requests (44%). The package manager they name most is pnpm (25 files).
AGENTS.md or CLAUDE.md?
Among these Hono products, 69 keep an AGENTS.md and 49 a CLAUDE.md. Across every product we checked, 320 keep both, and in 170 of those the CLAUDE.md only points to the AGENTS.md (a symlink or a line like @AGENTS.md), so there's one file to maintain. Codex, Cursor, Copilot and others read AGENTS.md; Claude Code reads CLAUDE.md.
How long is a typical Hono AGENTS.md?
The median is 1,207 words in these 73 files; across all 641 files we read, half are between 425 and 1,665 words.
How this is counted: the GitHub repos of open-source products built with Hono, pushed to in the 180 days before 2026-10-12. We read each repo's AGENTS.md, CLAUDE.md and other agent files; what's published here is counts and links, not their text. All files, by the numbers.