CLAUDE.md

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

Project Overview

SpecVital Worker - Background job processing service for analyzing test files in GitHub repositories

Queue-based async worker (River on PostgreSQL)
External parser:
```
github.com/specvital/core
```

Workers

Worker	Kind	Description
AnalyzeWorker	`analysis:analyze`	Parse test files from GitHub repos
SpecViewWorker	`specview:generate`	AI-powered test spec documentation (see below)

SpecView Worker

Generates human-readable spec documents from test files using Gemini AI.

Phase 1: Domain/feature classification (gemini-2.5-flash)
Phase 2: Test name → behavior conversion (gemini-2.5-flash-lite, parallel)
Cache: Content hash-based deduplication
Reliability: Circuit breaker, rate limiting, exponential backoff

Required env vars:

```
GEMINI_API_KEY
```
: Gemini API key
```
GEMINI_PHASE1_MODEL
```
: Phase 1 model (default: gemini-2.5-flash)
```
GEMINI_PHASE2_MODEL
```
: Phase 2 model (default: gemini-2.5-flash-lite)

Documentation Map

Context	Reference
Architecture / Data flow	`docs/en/`
Design decisions (why this way)	`docs/en/adr/`
Coding rules / Test patterns	`.claude/rules/`

Commands

Before running commands, read

justfile

or check available commands via

just --list

Project-Specific Rules

Auto-Generated Files (NEVER modify)

src/internal/infra/db/{queries.sql.go,models.go,db.go}

Workflow:
```
just dump-schema
```
→
```
just gen-sqlc
```

External Dependency

Parsing logic lives in
```
github.com/specvital/core
```
, NOT here
For parser changes → open issue in core repo first

Build Artifacts Cleanup

```
just build
```
outputs binaries to
```
bin/
```
directory
After build verification, ALWAYS clean up:
```
rm -rf bin/
```
NEVER commit
```
bin/
```
directory (already in .gitignore)

Common Workflows

DB Schema Changes

Modify schema in specvital-infra repo
```
just dump-schema
```
→
```
just gen-sqlc
```
Update
```
adapter/repository/
```
implementation

Adding New Worker

Define worker in
```
adapter/queue/
```
Register in
```
app/container.go
```
Write tests

Project Overview

SpecVital Worker - Background job processing service for analyzing test files in GitHub repositories

Queue-based async worker (River on PostgreSQL)

External parser:

github.com/specvital/core

Worker	Kind	Description
AnalyzeWorker	`analysis:analyze`	Parse test files from GitHub repos
SpecViewWorker	`specview:generate`	AI-powered test spec documentation (see below)

Generates human-readable spec documents from test files using Gemini AI.

Phase 1: Domain/feature classification (gemini-2.5-flash)

Phase 2: Test name → behavior conversion (gemini-2.5-flash-lite, parallel)

Cache: Content hash-based deduplication

Reliability: Circuit breaker, rate limiting, exponential backoff

Required env vars:

GEMINI_API_KEY

: Gemini API key

GEMINI_PHASE1_MODEL

: Phase 1 model (default: gemini-2.5-flash)

GEMINI_PHASE2_MODEL

: Phase 2 model (default: gemini-2.5-flash-lite)

Context

Reference

Architecture / Data flow

docs/en/

Design decisions (why this way)

docs/en/adr/

Coding rules / Test patterns

.claude/rules/

Project-Specific Rules

src/internal/infra/db/{queries.sql.go,models.go,db.go}

Workflow:

just dump-schema

→

just gen-sqlc

Parsing logic lives in

github.com/specvital/core

, NOT here

For parser changes → open issue in core repo first

just build

outputs binaries to

bin/

CLAUDE.md

CLAUDE.md

Project Overview

Workers

SpecView Worker

Documentation Map

Commands

Project-Specific Rules

Auto-Generated Files (NEVER modify)

External Dependency

Build Artifacts Cleanup

Common Workflows

DB Schema Changes

Adding New Worker

Related Skills

Markdown Converter

Nano Banana Pro

1password

CLAUDE.md

Project Overview

Workers

SpecView Worker

Documentation Map

Commands

Project-Specific Rules

Auto-Generated Files (NEVER modify)

External Dependency

Build Artifacts Cleanup

Common Workflows

DB Schema Changes

Adding New Worker