Templates: web app and Python library

By agent-playbook · 0 stars

Placeholders in `<angle brackets>`. Headings shown at level 3; any level works.

### TypeScript web app

~~~markdown
# AGENTS.md

<Name> is a <Next.js/React/Vue> web app with a <REST/tRPC/GraphQL> API in `src/server`. Node <22>, pnpm.

### Commands
- Install: `pnpm install`
- Dev server: `pnpm dev` (http://localhost:3000)
- All tests: `pnpm test` | One file: `pnpm test -- src/path/file.test.ts`
- E2E: `pnpm e2e` (needs dev server running)
- Lint + types: `pnpm lint && pnpm typecheck`
- Format: `pnpm format`

### Layout
- `src/app/` routes and pages; `src/components/` shared UI; `src/server/` API and DB access.
- `src/gen/` is generated by `pnpm codegen`; never edit by hand.

### Conventions
- TypeScript strict; no `any` (use `unknown` and narrow).
- Validate all external input with the zod schemas in `src/schemas/`.
- Server code never imports from `src/components/`.
- Styling: <Tailwind>; no inline style objects.
- Data fetching: <server components / React Query>; no fetch in `useEffect`.

### Testing
- Unit tests sit next to the file: `foo.ts` -> `foo.test.ts`.
- Bug fixes start with a failing test.
- Do not mock the database in integration tests; use `pnpm db:test`.

### Boundaries
- Ask first: new dependencies, schema migrations, CI changes, auth code.
- Never: commit `.env*`, disable lint rules inline, edit `src/gen/`.

### Git
- Branch from `main`; Conventional Commits (`feat:`, `fix:`, `chore:`).

### Done means
`pnpm lint && pnpm typecheck && pnpm test` pass, and new behaviour has a test.
~~~

### Python library

~~~markdown
# AGENTS.md

<package> is a Python library for <purpose>. Supports Python <3.10-3.13>. Managed with uv.

### Commands
- Setup: `uv sync --all-extras`
- Tests: `uv run pytest` | One test: `uv run pytest tests/test_x.py::test_name -q`
- Lint + format: `uv run ruff check --fix . && uv run ruff format .`
- Types: `uv run mypy src`
- Docs: `uv run mkdocs serve`

### Layout
- Source in `src/<package>/` (src layout); tests in `tests/` mirror the source tree.
- Public API is whatever `src/<package>/__init__.py` exports.

### Conventions
- Type hints on all public functions; docstrings in <Google> style.
- No new runtime dependencies without discussion; optional features go in extras.
- Keep the public API backward compatible; deprecate with `warnings.warn(..., DeprecationWarning)` for one minor release first.
- Raise the library's own exceptions from `errors.py`, not bare `Exception`.

### Testing
- Every public function has tests, including edge cases and error paths.
- No network or filesystem outside `tmp_path` in tests.

### Boundaries
- Ask first: public API changes, dropping a Python version, new dependencies.
- Never: bump the version or edit `CHANGELOG.md` release headings (release tooling does this).

### Done means
Ruff, mypy, and pytest pass; public changes have a `CHANGELOG.md` entry under "Unreleased".
~~~