Revise AGENTS.md to streamline editing policy and documentation structure. Emphasize concise project-specific guidance and link to detailed agent documentation in docs/agents/.

kentcdodds · kentcdodds · commit 5dbf45c91171 · 2026-02-23T10:40:40.000-07:00
diff --git a/AGENTS.md b/AGENTS.md
@@ -1,47 +1,22 @@
 # AGENTS.md
 
-## Cloud-specific instructions
+This file is included in full context for every agent conversation. Keep it
+tiny and stable.
 
-### Overview
+## Editing policy
 
-This is Kent C. Dodds' personal website (kentcdodds.com) — a React Router v7 app
-with Express, SQLite (via Prisma), and extensive MSW mocks for all external
-APIs.
+- Avoid adding operational details to `AGENTS.md`.
+- Only update `AGENTS.md` to reference other docs/files.
+- Put project callouts and workflow details in `docs/agents/` and link them from
+  here.
 
-### Prerequisites
+## Agent docs (source of truth)
 
-- **Node.js 24** is required (`engines` field in `package.json`). Install via
-  `nvm install 24 && nvm alias default 24`.
-- The `.npmrc` sets `legacy-peer-deps=true`; `npm install` respects this
-  automatically.
+- `docs/agents/project-context.md` (setup, commands, project-specific caveats)
+- `docs/agents/code-style.md`
+- `docs/agents/testing-principles.md`
 
-### Key commands
-
-Standard dev commands are documented in `README.md` and `CONTRIBUTING.md`. Quick
-reference:
-
-| Task            | Command                                                                           |
-| --------------- | --------------------------------------------------------------------------------- |
-| Dev server      | `npm run dev` (starts on port 3000 with `MOCKS=true`)                             |
-| Lint            | `npm run lint`                                                                    |
-| Typecheck       | `npm run typecheck`                                                               |
-| Unit tests      | `npm run test -- --watch=false`                                                   |
-| E2E tests       | `npm run test:e2e:dev` (requires Playwright browsers: `npm run test:e2e:install`) |
-| DB reset + seed | `npx prisma@7 migrate reset --force` then `npx tsx other/runfile prisma/seed.ts`  |
-
-### Non-obvious caveats
-
-- **Dev server is not a TTY**: `server/dev-server.js` detects non-TTY and
-  disables keyboard shortcuts. This is expected in cloud agent terminals.
-- **All external APIs are mocked** via MSW when `MOCKS=true` (the default in
-  dev). No real API keys are needed for local development — the `.env.example`
-  values are sufficient.
-- **SQLite is file-based**: The database file lives at `prisma/sqlite.db`. No
-  external database server is required.
-- **Cache database**: A separate SQLite cache DB is created at `other/cache.db`.
-  It's populated on first request or via `npm run prime-cache:mocks`.
-- **Patch-package**: Three Remix packages are patched during `postinstall`
-  (patches in `other/patches/`). If you see patch errors after dependency
-  changes, check those patches.
-- **Content is filesystem-based**: Blog posts are MDX files in `content/blog/`.
-  Changes to content files are auto-detected by the dev server's file watcher.
+If you discover a new sharp edge, workflow, or non-obvious project behavior,
+update the relevant doc(s) in `docs/agents/` so future agent runs are faster and
+more correct. Keep callouts organized under clear headings and prefer concise,
+project-specific guidance over generic advice.
diff --git a/docs/agents/code-style.md b/docs/agents/code-style.md
@@ -0,0 +1,49 @@
+# Code style
+
+Apply these rules to all new or edited code. When in doubt, match the existing
+file style first, then run the formatter.
+
+## Function forms
+
+- Prefer function declarations for named, reusable functions.
+- Use arrow functions for callbacks and inline handlers.
+- Use object method shorthand for multi-line object methods.
+
+## Array types
+
+- Prefer `Array<T>` and `ReadonlyArray<T>` over `T[]`.
+- This avoids precedence pitfalls in union types and keeps type reads clearer.
+
+## Exports
+
+- Prefer named exports.
+- Use default exports only when a framework contract requires them.
+
+## Imports
+
+- Prefer repo-root `#...` imports (configured via `package.json` `"imports"`)
+  over parent-relative `../...` paths.
+- Keep `./...` imports for same-folder files.
+- Generated files (for example `types/worker-configuration.d.ts`) are allowed to
+  be exceptions; do not edit them by hand.
+
+## Type conventions
+
+- Prefer `type` aliases for object shapes and unions.
+- Use `interface` only when you need declaration merging or public extension
+  points.
+- Prefer inline type definitions in parameters over named types unless sharing
+  is necessary. When a one-off named type is useful, consider `Parameters<>` (or
+  similar utility types) instead.
+- Use `satisfies` when exporting objects that must match framework contracts.
+
+## Absence values
+
+- Use `null` for explicit "no value" in local state or API responses.
+- Use `undefined` for optional or omitted fields, and avoid mixing within one
+  API.
+
+## References
+
+- https://kentcdodds.com/blog/function-forms
+- https://tkdodo.eu/blog/array-types-in-type-script
diff --git a/docs/agents/project-context.md b/docs/agents/project-context.md
@@ -0,0 +1,36 @@
+# Project context
+
+This is Kent C. Dodds' personal website (kentcdodds.com) — a React Router v7 app
+with Express, SQLite (via Prisma), and extensive MSW mocks for all external APIs.
+
+## Prerequisites
+
+- Node.js 24 is required (`engines` in `package.json`).
+  - Install via `nvm install 24 && nvm alias default 24`.
+
+## Key commands
+
+Standard dev commands are documented in `README.md` and `CONTRIBUTING.md`. Quick
+reference:
+
+| Task            | Command                                                                           |
+| --------------- | --------------------------------------------------------------------------------- |
+| Dev server      | `npm run dev` (starts on port 3000 with `MOCKS=true`)                             |
+| Lint            | `npm run lint`                                                                    |
+| Typecheck       | `npm run typecheck`                                                               |
+| Unit tests      | `npm run test`                                                                    |
+| E2E tests       | `npm run test:e2e:dev` (requires Playwright browsers: `npm run test:e2e:install`) |
+| DB reset + seed | `npx prisma@7 migrate reset --force` then `npm run runfile -- prisma/seed.ts`     |
+
+## Non-obvious caveats
+
+- All external APIs are mocked via MSW when `MOCKS=true` (the default in dev). No
+  real API keys are needed for local development; `.env.example` values are
+  sufficient.
+- SQLite is file-based: the database file lives at `prisma/sqlite.db`. No
+  external database server is required.
+- Cache database: a separate SQLite cache DB is created at `other/cache.db`.
+  It's populated on first request or via `npm run prime-cache:mocks`.
+- Content is filesystem-based: blog posts are MDX files in `content/blog/`.
+  Changes to content files are auto-detected by the dev server's file watcher.
+
diff --git a/docs/agents/testing-principles.md b/docs/agents/testing-principles.md
@@ -0,0 +1,76 @@
+# Testing principles
+
+This codebase favors small, readable tests with explicit setup and minimal
+magic.
+
+## Principles
+
+- Prefer flat test files: use top-level `test(...)` and avoid `describe`
+  nesting.
+- Avoid shared setup like `beforeEach`/`afterEach`; inline setup per test.
+- Don't write tests for what the type system already guarantees.
+- Use disposable objects only when there is real cleanup. If no cleanup, skip
+  `using` and `Symbol.dispose`.
+- Build helpers that return ready-to-run objects (factory pattern), not globals.
+- Keep test intent obvious in the name: "auth handler returns 400 for invalid
+  JSON".
+- Write tests so they could run offline if necessary: avoid relying on the
+  public internet and third-party services; prefer local fakes/fixtures.
+- Prefer fast unit tests for server logic; keep e2e tests focused on journeys.
+- Run server tests with `bun test server` to avoid Playwright spec discovery.
+
+## Examples
+
+### `Symbol.dispose` with `using`
+
+```ts
+import { test, expect } from 'bun:test'
+
+const createTempFile = () => {
+	const path = `/tmp/test-${crypto.randomUUID()}.txt`
+	Bun.write(path, 'hello')
+
+	return {
+		path,
+		[Symbol.dispose]: () => {
+			try {
+				Bun.file(path).delete()
+			} catch {
+				// Cleanup should never fail the test.
+			}
+		},
+	}
+}
+
+test('reads a temp file', () => {
+	using tempFile = createTempFile()
+	const contents = Bun.file(tempFile.path).text()
+	return contents.then((text) => expect(text).toBe('hello'))
+})
+```
+
+### `Symbol.asyncDispose` with `await using`
+
+```ts
+import { test, expect } from 'bun:test'
+
+const createDisposableServer = async () => {
+	const server = Bun.serve({
+		port: 0,
+		fetch: () => new Response('ok'),
+	})
+
+	return {
+		url: `http://localhost:${server.port}`,
+		[Symbol.asyncDispose]: async () => {
+			await server.stop()
+		},
+	}
+}
+
+test('fetches from a disposable server', async () => {
+	await using server = await createDisposableServer()
+	const response = await fetch(server.url)
+	expect(await response.text()).toBe('ok')
+})
+```
diff --git a/server/dev-server.js b/server/dev-server.js
@@ -1,6 +1,9 @@
 import * as readline from 'node:readline'
+import { stripVTControlCharacters, styleText } from 'node:util'
 import { execa } from 'execa'
 
+process.env.NODE_ENV ??= 'development'
+
 const tryRunCommand = async (command, args, input) => {
 	try {
 		await execa(command, args, input ? { input } : undefined)
@@ -38,7 +41,8 @@ const copyToClipboard = async (value) => {
 	return tryRunCommand('xclip', ['-selection', 'clipboard'], value)
 }
 
-const stripAnsi = (value) => value.replace(/\x1b\[[0-9;]*m/g, '')
+const canStyle = Boolean(process.stdout.isTTY && process.stdout.hasColors?.())
+const color = (style, text) => (canStyle ? styleText(style, text) : text)
 
 if (process.env.NODE_ENV === 'production') {
 	// the file may not be there yet
@@ -52,7 +56,7 @@ if (process.env.NODE_ENV === 'production') {
 	let lastLocalUrl = `http://localhost:${process.env.PORT || 3000}`
 
 	const extractLocalUrl = (text) => {
-		const cleaned = stripAnsi(text)
+		const cleaned = stripVTControlCharacters(text)
 		const localMatch = cleaned.match(/Local:\s+(\S+)/)
 		if (localMatch?.[1]) {
 			return localMatch[1]
@@ -123,22 +127,25 @@ if (process.env.NODE_ENV === 'production') {
 		startChild()
 	}
 
-	const printHelp = () => {
+	function printHelp() {
 		console.log(
 			[
 				'Supported keys:',
-				`  o - open app (${lastLocalUrl})`,
-				`  c - copy url (${lastLocalUrl})`,
-				'  r - restart app',
-				'  h - help',
-				'  q - exit (or Ctrl+C)',
-			].join('\n'),
+				`  ${color('green', 'o')} - open app (${lastLocalUrl})`,
+				`  ${color('cyan', 'c')} - copy url (${lastLocalUrl})`,
+				`  ${color('magenta', 'r')} - restart app`,
+				`  ${color('yellow', 'h')} - help`,
+				`  ${color('red', 'q')} - exit (or Ctrl+C)`,
+			].join('\n')
 		)
 	}
 
 	startChild()
 
-	if (process.stdin.isTTY && process.stdout.isTTY) {
+	const shortcutsEnabled = Boolean(process.stdin.isTTY && process.stdout.isTTY)
+
+	if (shortcutsEnabled) {
+		printHelp()
 		readline.emitKeypressEvents(process.stdin)
 		process.stdin.setRawMode(true)
 		process.stdin.resume()
