Skip to content

AGENTS.md

Latest commit

 

History

History
288 lines (189 loc) · 9.99 KB

AGENTS.md

File metadata and controls

288 lines (189 loc) · 9.99 KB

AGENTS.md

This file defines normative development rules for this repository.

All RFC 2119 keywords (MUST, MUST NOT, SHOULD, etc.) are to be interpreted as described in: https://www.rfc-editor.org/rfc/rfc2119.html

General

  • NEVER USE MEMORY CACHE.
  • ALWAYS READ CURRENT FILE STATE FROM DISK OR THE ACTIVE CODE EDITOR BUFFER.
  • AGENT MEMORY IS A FORBIDDEN STATE / REALITY SOURCE.
  • When uncertain about behavior, prefer primary specifications and vendor documentation over assumptions.
  • Do not invent behavior. Verify it.

Verification

Run the smallest set of checks that covers your change.

  • If you change runtime logic or public API: npm run test.
  • If you touch benchmarks or performance-sensitive code: npm run bench.
  • If you modify TypeScript build config or emit-related logic: npm run build.
  • If you change formatting or add files: npm run format.

If a required command cannot run in the current environment, state that explicitly and explain why.

Architectural Principles

1. Minimal Surface Area

Every directory under src/ represents a single logical unit.

Each unit:

  • MUST contain at most one root-level .ts file.
  • MUST export at most one top-level class OR one top-level function.
  • SHOULD remain under ~100 lines of executable logic (imports and type-only declarations excluded).
  • The ~100 line budget counts executable statements only and excludes imports, type-only exports, comments, and blank lines.
  • MUST have a single, clear responsibility.

If complexity grows:

  • Extract a subdirectory.
  • Or prefer an external dependency.

Large files are a design failure, not an achievement.

2. Package Preference Rule

Reimplementation of common infrastructure logic is forbidden.

  • Prefer mature, audited packages over ad-hoc boilerplate.
  • Do not reimplement encoding, parsing, crypto primitives, validation frameworks, etc.
  • Local code MUST focus on domain logic, not infrastructure recreation.

If boilerplate appears repeatedly, dependency evaluation is mandatory.

Dependency evaluation MUST consider maintenance activity within the last 12 months, license compatibility, known security advisories, API stability, and real-world adoption. Record the decision in change notes or the PR description.

3. Helpers

If helpers are unavoidable:

  • They MUST reside under a .helpers/ directory.
  • They MUST be minimal and narrowly scoped.
  • They MUST NOT evolve into a general-purpose utility framework.
  • They MUST NOT contain domain logic.

A growing .helpers/ directory indicates architectural drift.

Domain logic means business rules, policy decisions, and data model validation specific to this package. It excludes encoding/decoding, crypto, serialization, I/O, and generic data plumbing.

4. Types

Reusable structural types MUST be isolated.

Structure:


.types/
TypeName/
type.ts

Rules:

  • Each reusable type gets its own folder.
  • The file MUST be named type.ts.
  • No executable logic is allowed in .types/.
  • Types define contracts, not behavior.

5. Errors

Errors MUST be explicit, semantic, and typed.

Structure:


.errors/
class.ts

Pattern:

export type PackageNameCode = 'SOME_ERROR_CODE' | 'ANOTHER_ERROR_CODE'

export class PackageNameError extends Error {
  readonly code: PackageNameCode

  constructor(code: PackageNameCode, message?: string) {
    const detail = message ?? code
    super(`{@scope/package-name} ${detail}`)
    this.code = code
    this.name = 'PackageNameError'
  }
}

Rules:

  • Error codes MUST be semantic string literals.
  • Error codes MUST be SCREAMING_SNAKE_CASE and use short domain prefixes when needed (example: CRYPTO_INVALID_KEY).
  • Throwing raw Error is forbidden.
  • Every thrown error MUST map to an explicit error code.
  • Error messages MUST include package scope.

Errors are part of the public contract.

6. Forbidden Patterns

  • No multi-responsibility modules
  • No utility dumping grounds
  • No silent boilerplate replication
  • No implicit global state
  • No hidden cross-layer imports

Architecture must remain explicit and auditable.

Example disallowed: .helpers/ importing from src/domain/*, or .types/ importing from runtime code.

Specification Discipline (index.html)

When working on (cwd | root | .)/index.html:

This applies only when index.html exists or a task explicitly asks to create it. Otherwise, do not create or modify it.

Authoring Tool

Use ReSpec:

Normative References

Infra / Language

Identifiers / Credentials

JSON-LD / RDF

WebCrypto

JOSE

HTTP

Ideas

Cloudflare Workers Discipline

Your knowledge of Cloudflare Workers MAY be outdated.

Before any task involving Workers, KV, R2, D1, Durable Objects, Queues, Vectorize, Workers AI, Hyperdrive, or Agents:

  • Retrieve current documentation.
  • Verify platform limits.
  • Confirm API behavior against official docs.
  • If documentation cannot be retrieved due to environment restrictions, request permission to browse and state the limitation.

Documentation Entry Points

Limits

Always consult official limits pages before reasoning about quotas.

Commands

Command Purpose
npx wrangler dev Local development
npx wrangler deploy Deploy to Cloudflare
npx wrangler types Generate TypeScript types

After modifying bindings in wrangler.toml or wrangler.jsonc, run:

npx wrangler types

Philosophy

Small modules. Explicit contracts. Typed errors. Spec-first reasoning. Dependency over reinvention. No hidden state.

Architecture is a constraint system, not a suggestion.