Path-Specific Rules

O Path-Specific Rules e um sistema de regras condicionais do ChatCLI que aplica instruções automaticamente com base nos caminhos de arquivos sendo discutidos ou editados na conversa. Em vez de carregar todas as regras sempre, o sistema detecta quais arquivos estão em contexto e injeta apenas as regras relevantes.

Path Rules complementam o sistema de bootstrap (RULES.md). Enquanto RULES.md define regras globais, Path Rules define regras específicas para partes do codebase.

Conceito

A ideia e simples: diferentes partes do codebase tem diferentes convencoes. Código Go segue regras diferentes de templates HTML. Testes tem padroes diferentes de código de produção. Path Rules permite definir tudo isso de forma granular.

Conversa menciona auth/handler.go
      |
      v
Path matcher: "auth/**" -> auth-rules.md
Path matcher: "*.go"    -> go-rules.md
      |
      v
Regras injetadas no system prompt
(apenas as relevantes)

Estrutura de Arquivos

As regras ficam no diretório .chatcli/rules/ (workspace) ou ~/.chatcli/rules/ (global):

.chatcli/rules/
|-- go-rules.md          # Regras para arquivos Go
|-- test-rules.md        # Regras para arquivos de teste
|-- api-rules.md         # Regras para o modulo de API
|-- migration-rules.md   # Regras para migrations de banco
+-- security-rules.md    # Regras para modulos de segurança

Formato do Arquivo

Cada arquivo de regra e um Markdown com frontmatter YAML contendo o campo paths:

---
paths:
  - "*.go"
  - "**/*.go"
description: "Regras para código Go"
---
# Regras Go

## Estilo
- Use `gofmt` como formatador padrão
- Nomes de variáveis em camelCase
- Interfaces com sufixo "-er" quando possuem um único método (Reader, Writer)

## Erros
- Sempre verifique erros retornados
- Use `fmt.Errorf("context: %w", err)` para wrapping
- Nunca use `panic()` em código de produção

## Testes
- Use table-driven tests
- Nomeie subtestes descritivamente
- Use `t.Helper()` em funções auxiliares de teste

Precedencia

Workspace vs Global
Multiplas regras

Regras existem em dois níveis com workspace tendo prioridade:

Nível	Diretório	Prioridade
Workspace	`.chatcli/rules/*.md`	Alta (sobrescreve global)
Global	`~/.chatcli/rules/*.md`	Baixa (fallback)

Se um arquivo de regra com o mesmo nome existir em ambos os níveis, a versão do workspace prevalece.

Quando um arquivo corresponde a múltiplos padroes, todas as regras correspondentes são injetadas:

Arquivo: auth/handler_test.go

Regras aplicadas:
  1. go-rules.md        (match: *.go)
  2. test-rules.md      (match: *_test.go)
  3. api-rules.md       (match: auth/**)

As regras são concatenadas na ordem em que os arquivos de regra são encontrados (alfabetica).

Glob Matching

O campo paths usa padroes glob para corresponder caminhos de arquivos:

Padrão	Corresponde a
`*.go`	Arquivos Go no diretório raiz
`*/.go`	Arquivos Go em qualquer subdiretorio
`*_test.go`	Arquivos de teste Go
`src/**`	Todos os arquivos dentro de `src/`
`auth/**`	Todos os arquivos dentro de `auth/`
`*.{ts,tsx}`	Arquivos TypeScript e TSX
`migrations/*.sql`	Arquivos SQL em `migrations/`
`Dockerfile*`	Dockerfiles (Dockerfile, Dockerfile.prod, etc.)

Use ** para correspondencia recursiva em subdiretorios. O padrão *.go corresponde apenas no diretório raiz, enquanto **/*.go corresponde em toda a arvore.

Lazy Loading

Path Rules usa lazy loading baseado em dicas da conversa:

Detecção de contexto

O ChatCLI analisa as mensagens recentes e tool calls para identificar quais arquivos estão em contexto (lidos, editados, mencionados).

Match de padroes

Os caminhos detectados são comparados contra os padroes paths de cada arquivo de regra.

Injecao seletiva

Apenas as regras que correspondem a arquivos em contexto são injetadas no system prompt.

Atualizacao dinamica

A cada turno, os padroes são re-avaliados. Novas regras podem ser injetadas e regras irrelevantes podem ser removidas.

Lazy loading garante que o system prompt não fique sobrecarregado com regras irrelevantes. Apenas as regras necessarias para os arquivos em discussao são carregadas, economizando tokens.

Exemplos de Regras

Go
Testes
Segurança
Migrations

.chatcli/rules/go-rules.md:

---
paths:
  - "**/*.go"
description: "Convencoes Go do projeto"
---
# Regras Go

- Use `errors.New()` ou `fmt.Errorf()` para erros, nunca strings cruas
- Funções exportadas DEVEM ter comentario godoc
- Use `context.Context` como primeiro parâmetro quando aplicavel
- Prefira `sync.Mutex` a channels para estado compartilhado simples
- Não use `init()` exceto para registro de drivers

.chatcli/rules/test-rules.md:

---
paths:
  - "**/*_test.go"
  - "**/*.test.ts"
  - "**/*.spec.ts"
description: "Padroes para arquivos de teste"
---
# Regras de Teste

- Use table-driven tests em Go
- Nomeie subtestes com descricoes claras em ingles
- Evite mocks excessivos — prefira fakes ou stubs simples
- Cada teste deve ser independente e idemponente
- Use `t.Parallel()` quando o teste não depende de estado global

.chatcli/rules/security-rules.md:

---
paths:
  - "auth/**"
  - "security/**"
  - "**/middleware/auth*"
description: "Regras de segurança para modulos criticos"
---
# Regras de Segurança

- NUNCA logue tokens, senhas ou API keys
- Use `crypto/rand` para geracao de tokens, NUNCA `math/rand`
- Valide TODOS os inputs do usuário antes de processar
- Use prepared statements para queries SQL (prevencao de injection)
- Implemente rate limiting em endpoints de autenticação
- Tokens JWT devem ter expiracao máxima de 1 hora

.chatcli/rules/migration-rules.md:

---
paths:
  - "migrations/**"
  - "db/migrations/**"
description: "Regras para migrations de banco de dados"
---
# Regras de Migrations

- Sempre inclua operação UP e DOWN
- Nomes no formato: YYYYMMDDHHMMSS_descrição.sql
- Evite ALTER TABLE em tabelas grandes sem downtime plan
- Use transações explicitas (BEGIN/COMMIT)
- Não use DROP COLUMN em produção sem deprecacao previa
- Adicione indices em campos usados em WHERE e JOIN

Visualizando Regras Ativas

Você pode verificar quais regras estão ativas no momento:

User: Quais path rules estão ativas?

Agent: Com base nos arquivos em contexto, as seguintes regras estão ativas:

  Active Path Rules:
    go-rules.md       (match: auth/handler.go, auth/jwt.go)
    security-rules.md (match: auth/handler.go, auth/jwt.go)
    test-rules.md     (match: auth/handler_test.go)

  Total: 3 rules, ~450 tokens

Boas Praticas

Regras específicas

Defina padroes de path precisos. Regras muito amplas (**/*) desperdicam tokens em contextos irrelevantes.

Regras concisas

Mantenha cada arquivo de regra curto e focado. Regras longas consomem mais tokens.

Versione no Git

Coloque .chatcli/rules/ no repositório para compartilhar com a equipe.

Combine com RULES.md

Use RULES.md para regras globais e Path Rules para regras específicas por area do código.

Início

Primeiros Passos

Conceitos Fundamentais

Funcionalidades

Segurança

Suporte

Path-Specific Rules

Conceito

Estrutura de Arquivos

Formato do Arquivo

Precedencia

Glob Matching

Lazy Loading

Exemplos de Regras

Visualizando Regras Ativas

Boas Praticas

Regras específicas

Regras concisas

Versione no Git

Combine com RULES.md

Próximos Passos

Bootstrap e Memória

Agentes Customizaveis

​Conceito

​Estrutura de Arquivos

​Formato do Arquivo

​Precedencia

​Glob Matching

​Lazy Loading

​Exemplos de Regras

​Visualizando Regras Ativas

​Boas Praticas

Regras específicas

Regras concisas

Versione no Git

Combine com RULES.md

​Próximos Passos

Bootstrap e Memória

Agentes Customizaveis

Conceito

Estrutura de Arquivos

Formato do Arquivo

Precedencia

Glob Matching

Lazy Loading

Exemplos de Regras

Visualizando Regras Ativas

Boas Praticas

Próximos Passos