Skip to content

CLAUDE.md

Latest commit

 

History

History
37 lines (27 loc) · 1.72 KB

CLAUDE.md

File metadata and controls

37 lines (27 loc) · 1.72 KB
Raw

CLAUDE.md — retro-reflect-bot

Architecture

Three CLI commands (gather → generate → submit) share disk state under out/<run-id>/. Each command is a thin wrapper around a pipeline function in src/pipeline/. Data sources implement the DataSource interface (see src/sources/types.ts).

Key invariants

  • Never call exec/shell directly. All gh calls go through runGh (src/sources/gh-run.ts) which uses execFile and runs args through validateGhArgs first.
  • All LLM responses go through extractJson (throws) or extractJsonOrNull (returns null) — see src/generator/extractJson.ts.
  • Every cross-command artifact (meta.json, cards.json, context.json) is Zod-validated before use. Schemas live near the writer, but are imported by the reader.
  • Retry only network/5xx/429 errors. GraphQL application errors and 4xx auth errors are NOT retried — see defaultIsRetryable in src/util/retry.ts.

Testing

pnpm verify runs typecheck + all tests. Run before any commit. Tests inject fakes (mock client, mock exec, mock streams). Do NOT mock module internals or spy on logger.

Common extensions

  • New data source: implement DataSource in src/sources/, register in src/sources/registry.ts, add tests in test/sources/.
  • Change default model or token budget: edit src/config/defaults.ts (single source of truth).
  • Change gh allowlist: edit src/sources/gh-allowlist.ts and add a test case.

Conventions

  • TypeScript strict mode + verbatimModuleSyntax. Use import type for type-only imports.
  • All local imports use .ts extensions (required by allowImportingTsExtensions).
  • Single shared logger from src/config/logger.ts — tagged consola instance.