CLAUDE.md · diff

git:20260310.825bf90 to git:20260331.126e1c0

82 added, 41 removed. Audit A to A.

- # TARSy Development Guidelines

+ # CLAUDE.md

- ## 🎯 General Coding Standards (All Languages)

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

- **MANDATORY**: For ALL coding tasks regardless of programming language, apply:

+ ## Project Overview

- - `.cursor/skills/karpathy-modified-guidelines/SKILL.md`

+ TARSy (Thoughtful Alert Response System) is an intelligent SRE system that processes alerts through parallel agent chains using MCP servers for multi-stage incident analysis and automated remediation. Hybrid Go + Python architecture: Go orchestrator handles business logic, session management, and real-time streaming; a stateless Python service manages LLM interactions over gRPC.

- These emphasize: think before coding, simplicity over complexity, surgical changes, goal-driven execution.

+ ## Build & Development Commands

- ## 🔍 Language-Specific Skills (Auto-Discovery)

+ ```bash

+ make doctor # Verify prerequisites (Go 1.25+, Python 3.13+, Node 24+, uv, Podman)

+ make setup # Install all deps + bootstrap config files

+ make dev # Start full dev environment (DB + LLM service + backend + dashboard)

+ make dev-stop # Stop all dev services

+ make build # Build Go binary

+ ```

- When working with code in a specific programming language:

+ ## Testing Commands

- ### Before writing, editing, or reviewing code

+ ```bash

+ make test # Run all tests (Go + Python + Dashboard)

+ make test-unit # Go unit tests only (pkg/...)

+ make test-go # All Go tests (unit + e2e) with coverage and race detector

+ make test-llm # Python LLM service tests (via uv/pytest)

+ make test-dashboard # Dashboard tests + TypeScript check

- 1. **Scan** `.cursor/skills/` directory for skills matching `<language>-*` pattern

- 2. **Read and apply** ALL matching skill files

- 3. **Apply patterns** from those skills automatically

+ # Single Go test

+ go test -v -race ./pkg/config/ -run TestSkillRegistry

+ go test -v -race ./pkg/config/ -run TestSkillRegistry/subtest_name

- ### Go (Golang)

+ # E2E tests (require Docker/Podman for PostgreSQL via Testcontainers)

+ go test -v -race -timeout 300s ./test/e2e/ -run TestE2E_Pipeline

+ ```

- Pattern: `golang-*`

+ ## Lint & Format

- Example current skills (scan directory for latest):

+ ```bash

+ make fmt # Format Go code (goimports + gofmt)

+ make lint # Run golangci-lint

+ make lint-fix # Lint with auto-fix

+ make check-all # Format + build + lint + all tests

+ ```

- - `golang-context-patterns` - Context handling (background ctx for writes, etc.)

- - `golang-error-handling` - Error wrapping, sentinel errors, custom errors

- - `golang-testing-patterns` - Table-driven tests, subtests

+ ## Code Generation

- **Future skills like `golang-performance`, `golang-concurrency` will be automatically discovered and applied.**

+ ```bash

+ make ent-generate # Regenerate Ent ORM code after schema changes in ent/schema/

+ make proto-generate # Regenerate Go + Python gRPC code from proto/llm_service.proto

+ make migrate-create NAME=add_feature # Create new DB migration (MUST run db-migration-review skill after)

+ ```

- ### Other Languages

+ ## Architecture

- Follow the same pattern:

+ ### Three-service split

- - Python: scan for `python-*`

- - TypeScript: scan for `typescript-*`

- - Rust: scan for `rust-*`

- - etc.

+ - **Go backend** (`cmd/tarsy/`, `pkg/`) -- Orchestrator, API server (Echo v5), worker pool, event streaming. Port 8080.

+ - **Python LLM service** (`llm-service/`) -- Stateless gRPC server routing to LLM providers (Gemini, OpenAI, Anthropic, xAI, Vertex AI). Port 50051.

+ - **React dashboard** (`web/dashboard/`) -- React 19 + TypeScript + Vite 7 + MUI 7 SPA. Port 5173.

- ## 🔧 Workflow Skills (Always Apply When Relevant)

+ ### Key Go packages (pkg/)

- These skills apply to specific workflows regardless of language:

+ | Package | Purpose |

+ |---------|---------|

+ | `agent/` | Agent framework: IteratingController, SingleShotController, ScoringController, prompt building, tool execution |

+ | `api/` | HTTP handlers (alerts, sessions, chat, review, memory, scoring, trace, timeline, system) |

+ | `config/` | YAML config loading with registries for agents, chains, MCP servers, providers, skills |

+ | `database/` | Ent client wrapper, migrations, GIN index hooks |

+ | `events/` | Real-time event pub via PostgreSQL LISTEN/NOTIFY + WebSocket |

+ | `queue/` | Worker pool with database-backed job claiming (FOR UPDATE SKIP LOCKED) |

+ | `mcp/` | MCP client factory and health monitoring |

+ | `memory/` | Investigation memory: pgvector embeddings, hybrid retrieval (semantic + keyword + RRF) |

+ | `services/` | Domain services (AlertService, SessionService, ChatService, ScoringService, MemoryService, etc.) |

+ | `masking/` | Data masking (K8s Secret detection + regex patterns) |

- - `db-migration-review` - **MANDATORY** after every `make migrate-create`. Reviews generated `.up.sql` for Atlas schema drift (dropped partial indexes, no-op recreations).

+ ### Data flow

- ## 📋 Available Commands

+ 1. Alert received via API -> queued in DB

+ 2. Worker claims session (FOR UPDATE SKIP LOCKED) -> executes agent chain

+ 3. Each agent iteration: Go builds conversation -> gRPC to Python LLM service -> streams response chunks back

+ 4. Tool calls executed by Go via MCP servers -> results appended -> next iteration

+ 5. Real-time updates via PostgreSQL LISTEN/NOTIFY -> WebSocket to dashboard

- When a user invokes a `/command-name`, scan `.cursor/commands/` for a matching `command-name.md` file, read it, and follow its instructions.

+ ### Database

- **Note**: Commands are only executed when explicitly requested by the user.

+ - **PostgreSQL 17 + pgvector** for vector similarity search

+ - **Ent ORM** for type-safe queries; schemas in `ent/schema/`

+ - **Atlas** for migration authoring; custom hooks add GIN indexes and partial unique indexes

+ - Migrations auto-applied on startup via `pkg/database/`

- ## 🚀 How This Works

+ ### Proto/gRPC

- This configuration is **future-proof**:

+ Single service definition in `proto/llm_service.proto` with streaming `Generate` RPC. Generated code lands in `proto/` (Go) and `llm-service/llm_proto/` (Python).

- - Add `golang-concurrency/SKILL.md` → automatically applied to Go code

- - Add `python-testing/SKILL.md` → automatically applied to Python code

- - No need to update CLAUDE.md when adding new skills

+ ### Configuration

- **Naming convention**: `<language>-<topic>/SKILL.md`

+ Config files in `deploy/config/`: `tarsy.yaml` (agents, chains, MCP servers), `llm-providers.yaml` (provider configs), `.env` (secrets/env vars). YAML files support Go template interpolation (`{{.VAR_NAME}}`).

- ## Application Order

+ ### E2E test infrastructure

- 1. **Always first**: karpathy-modified-guidelines

- 2. **Then**: All `<language>-*` skills for the current language (discovered automatically)

- 3. **On request**: Specific commands via `/command-name`

+ Tests in `test/e2e/` use a `TestApp` harness that boots a complete TARSy instance with Testcontainers PostgreSQL, a `ScriptedLLMClient` for deterministic LLM responses, and in-memory MCP servers. Test configs in `test/e2e/testdata/configs/`.

- Apply skills automatically without being asked.

+ ## Coding Standards

+ **MANDATORY**: Before writing, editing, or reviewing code, read and apply:

+ 1. `.cursor/skills/karpathy-modified-guidelines/SKILL.md` (always first -- think before coding, simplicity, surgical changes, goal-driven execution)

+ 2. All `.cursor/skills/<language>-*/SKILL.md` matching the language you're working in (e.g., `golang-*` for Go)

+ 3. `.cursor/skills/db-migration-review/SKILL.md` after every `make migrate-create`

+ Current Go skills: `golang-context-patterns`, `golang-error-handling`, `golang-testing-patterns`, `golang-type-safety`, `use-modern-go`. Scan `.cursor/skills/` for the latest set.