# CLAUDE.md

## Project Context

## Registro obrigatório de alterações

Ao concluir qualquer implementação, acrescentar uma única linha em
`admin/COMMIT-DETAILS.md` descrevendo resumidamente o que foi alterado. A
linha deve ser adicionada ao final do arquivo, sem apagar os registros
anteriores do lote. O resumo não pode conter segredos ou tokens. O
`admin/deploy.command` usa essas linhas na mensagem do commit e limpa o
arquivo somente depois de um commit bem-sucedido.

This is a software engineering project that uses mattpocock/skills for code quality and organization.

## Code Search: use the RAG first

This project has a code RAG at `rag/` (see [rag/README.md](rag/README.md)),
already indexed and kept in sync automatically (a `PostToolUse` hook
reindexes any edited file). Before grepping or reading whole files to find
something in `code/`, run:

```bash
rag/search_jhonny.sh "your query in natural language"
```

This returns exact `file:line-range` hits instead of forcing a full read of
large files — much cheaper in tokens. Use `--snippet` or `--full` when you
need to see the matched code, `--map` for a file inventory, and `--path`/
`--ext` to scope the search. Fall back to Grep/Glob only when the RAG has no
tunnel available (`rag/ensure_tunnel.sh` failed) or for exact-string
searches it isn't built for (e.g. searching non-code config not indexed).

## Mandatory skill — read before writing any Python in code/engine/

**`.agents/skills/boas-praticas-oo/SKILL.md` is not optional.** It is not
triggered by a request — apply it automatically on every Python file created,
edited, fixed, refactored or reviewed under `code/engine/`: PT-BR identifiers
for everything internal, docstrings on every module/class/public method,
single-responsibility classes, explicit dependency injection, specific
exceptions (never bare `except Exception`), input validation, and tests for
the behavior touched. See [CODING_STANDARDS.md](CODING_STANDARDS.md) for the
normative summary, and run its checklist (skill section 41) before calling
any Python change in `code/engine/` done.

## Available Skills

The following skills are available in this project (located in `.agents/skills/`):

### Code Quality & Architecture
- **`boas-praticas-oo`** - **Mandatory**, always-on. OO standards + PT-BR naming for all `code/engine/` Python (see above)
- **`/improve-codebase-architecture`** - Scan codebase for deepening opportunities
- **`/codebase-design`** - Design deep modules with simple interfaces
- **`/domain-modeling`** - Build shared vocabulary and domain model

### Testing & Code Review
- **`/tdd`** - Test-driven development with red-green-refactor loop
- **`/code-review`** - Two-axis review: Standards + Spec
- **`/diagnosing-bugs`** - Disciplined bug diagnosis loop
- **`/resolving-merge-conflicts`** - Resolve git conflicts hunk by hunk

### Global Skills (available via ~/.agents/skills/)
- 29 additional skills for engineering and productivity

## Usage

When working on this project, use these skills to:
1. **Improve architecture**: Run `/improve-codebase-architecture` to scan for improvements
2. **Design modules**: Use `/codebase-design` when creating new modules
3. **Model domain**: Use `/domain-modeling` to build shared vocabulary

## Code Standards

- Python in `code/engine/`: follow `.agents/skills/boas-praticas-oo/SKILL.md` and [CODING_STANDARDS.md](CODING_STANDARDS.md) — mandatory, not a suggestion
- Use shared domain vocabulary from CONTEXT.md
- Write tests before code (TDD)
- Review code changes with `/code-review`