beads/engdocs/CLAUDE.md
Julian Knutsen e9a12ed3b1
docs(test): make TESTING.md canonical (bd-mrs20) (#5226)
Consolidate test execution and design guidance around the smallest trustworthy seam, narrow doubles, semantic versus persistence conformance, strict E2E admission, and proportional verification. Convert the former philosophy documents to compatibility pointers.

Agent-Signature: codex-unknown-model-unknown-reasoning on behalf of CI Bot

Co-authored-by: CI Bot <ci@beads.test>
2026-08-01 02:30:21 -07:00

3.5 KiB

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

beads (command: bd) is a Dolt-powered issue tracker for AI-supervised coding workflows. Git integration is optional — see BEADS_DIR + --stealth for git-free operation. We dogfood our own tool.

IMPORTANT: See AGENTS.md for complete workflow instructions, bd commands, and development guidelines.

Architecture Overview

Three-Layer Design

  1. Storage Layer (internal/storage/)

    • Dolt in storage/dolt/ — version-controlled SQL database with cell-level merge
    • Common types and interfaces in storage.go
  2. Database Runtime Layer

    • Embedded mode runs Dolt in-process through internal/storage/embeddeddolt/
    • Server mode uses internal/doltserver/ and internal/storage/db/
    • Proxy and pidfile helpers live under internal/storage/db/
    • Storage-facing server adapters live under internal/storage/doltserver/
  3. CLI Layer (cmd/bd/)

    • Cobra-based commands (one file per command: create.go, list.go, etc.)
    • Direct database access (embedded mode for standalone, server mode for orchestrator)
    • All commands support --json for programmatic use
    • Main entry point in main.go

Storage Architecture

Beads uses Dolt as its storage backend — a version-controlled SQL database:

Dolt DB (.beads/dolt/)
    ↕ Dolt commits (automatic per write)
    ↕ Dolt push/pull (native sync)
Remote (Dolt remotes: DoltHub, S3, GCS, etc.)
  • Write path: CLI → Dolt → auto-commit to Dolt history
  • Read path: Direct SQL queries against Dolt
  • Sync: Dolt handles versioning and sync natively via bd dolt push / bd dolt pull
  • Hash-based IDs: Automatic collision prevention (v0.20+)

Core implementation:

  • Dolt storage: internal/storage/dolt/
  • Embedded runtime: internal/storage/embeddeddolt/
  • Server runtime: internal/doltserver/, internal/storage/db/, and internal/storage/doltserver/
  • Sync commands: cmd/bd/dolt_*.go, cmd/bd/sync_*.go

Key Data Types

See internal/types/types.go:

  • Issue: Core work item (title, description, status, priority, etc.)
  • Dependency: Four types (blocks, related, parent-child, discovered-from)
  • Label: Flexible tagging system
  • Comment: Threaded discussions
  • Event: Full audit trail

Development Command Source

Use the canonical TESTING.md for test commands, test design, and PR-readiness gates. This file should not duplicate command matrices or version-management workflows.

Do NOT use go build -o bd or go install directly — they create stale binaries that shadow ~/.local/bin/bd. Always use make install.

Testing

Testing guidance lives in TESTING.md. Architecture-specific notes for Claude are limited to where tests touch agent setup, hooks, or instruction-file generation.

Important Notes

  • Always read AGENTS.md first - it has the complete workflow
  • Check for duplicates proactively: bd duplicates --auto-merge
  • Use --json flags for all programmatic use

Key Files

  • AGENTS.md - Complete workflow and development guide (READ THIS!)
  • README.md - User-facing documentation
  • ADVANCED.md - Advanced features (rename, merge, compaction)
  • docs/core-concepts/labels.md - Complete label system guide
  • docs/reference/configuration.md - Configuration system

When Adding Features

See AGENTS.md "Adding a New Command" and "Adding Storage Features" sections for step-by-step guidance.