Pular para o conteúdo
Documentation

Personalize o agente de IA

Tudo nesta página é um arquivo local. Arquivos em .champrep/ em um repositório são compartilhados com sua equipe por meio do git; arquivos em $CONFIG/ai/ aplicam-se apenas a você, em todos os projetos. Quando um projeto e uma definição de usuário têm o mesmo nome, a definição do projeto prevalece.

Conteúdo do projeto em .champrep/ permanece inativo até que você confie no repositório. Consulte Confiança do repositório.

CHAMPREP.md contém instruções permanentes para o agente: como compilar e testar o projeto, convenções e itens a serem evitados. O agente lê, no início de cada sessão:

  • $CONFIG/ai/CHAMPREP.md, suas instruções pessoais para cada projeto;
  • CHAMPREP.md na raiz do projeto e em cada diretório, desde a raiz até onde o agente foi iniciado.

Se um diretório não tiver nenhum CHAMPREP.md, um AGENTS.md é utilizado em seu lugar.

AçãoComo
Crie um/init analisa o repositório e grava CHAMPREP.md, mantendo o conteúdo útil de um já existente AGENTS.md.
Adicionar uma notaInicie um prompt com #, por exemplo # run make lint before committing.
Visualizar ou editar/memory, ou /memory edit [user|project|FILE] para abri-lo em seu editor.

A memória da sua contaCHAMPREP AI, gerenciada nas configuraçõesCHAMPREP AI na web, também se aplica ao terminal. /memory mostra-o como somente leitura.

Um comando personalizado é um modelo de prompt em Markdown que você executa como /<name>.

LocalizaçãoEscopo
.champrep/commands/NAME.mdEste projeto
$CONFIG/ai/commands/NAME.mdVocê

Um arquivo em uma subpasta, como commands/git/commit.md, torna-se /git:commit. Crie um com /commands new NAME e liste-os com /commands.

---
description: Explain a failing test and propose a fix
argument-hint: <test name>
allowed-tools: [local_read_file, local_grep, local_bash]
---
Find the test named $1, run it, and explain why it fails.
Relevant notes: @docs/testing.md
Recent changes:
!`git log --oneline -5`
  • $ARGUMENTS é tudo o que vem após o nome do comando; $1, $2, … são argumentos únicos. Se o modelo não utilizar nenhum deles, os argumentos são anexados.
  • @path inclui um arquivo do espaço de trabalho. Arquivos confidenciais nunca são incluídos.
  • !`command` executa um comando quando você invoca o modelo. É solicitado que você aprove isso uma vez por modelo e novamente sempre que houver alterações.
  • allowed-tools limita as ferramentas para essa rodada e model substitui o modelo.

Uma habilidade é uma pasta contendo instruções e arquivos de suporte opcionais, que o agente carrega somente quando necessário. Até então, o modelo vê apenas o nome e a descrição da habilidade; por isso, muitas habilidades exigem muito pouco contexto.

LocalizaçãoEscopo
.champrep/skills/NAME/SKILL.mdEste projeto
$CONFIG/ai/skills/NAME/SKILL.mdVocê
---
description: Release checklist for this service
when_to_use: When the user asks to cut, tag, or publish a release
---
1. Confirm the changelog has an entry for the new version.
2. ...

/skills lista as habilidades, incluindo as da sua CHAMPREP AIconta. Execute uma diretamente com /<skill-name>.

Um agente personalizado é um subagente com suas próprias instruções, ferramentas e modelo.

LocalizaçãoEscopo
.champrep/agents/NAME.mdEste projeto
$CONFIG/ai/agents/NAME.mdVocê
---
name: test-writer
description: Writes and fixes unit tests. Use after a code change.
tools: [local_read_file, local_grep, local_glob, local_edit_file, local_bash]
permission_mode: accept-edits
isolation: worktree
---
You write focused unit tests that follow this project's existing style.
  • description informa ao agente principal quando deve delegar a ele.
  • tools restringe as ferramentas; omita-o para herdar as ferramentas da sessão.
  • permission_mode só pode tornar o agente mais restritivo do que a sua sessão.
  • isolation: worktree o executa em sua própria árvore de trabalho do Git.

Gerencie agentes com /agents create|edit|delete NAME. Inicie uma sessão como um agente com champrep ai --agent NAME, ou envie um prompt para ele com @NAME prompt. Consulte Subagentes.

Os ganchos são comandos de shell que o CLIexecuta em determinados momentos de uma sessão, por exemplo, para formatar arquivos após uma edição ou para bloquear determinados comandos.

EventoÉ executado
SessionStartQuando uma sessão é iniciada.
UserPromptSubmitAntes do envio de uma solicitação. Pode bloqueá-la ou adicionar contexto.
PreToolUseAntes da execução de uma ferramenta local. Pode bloqueá-la.
PostToolUseApós a execução de uma ferramenta local. Pode adicionar feedback ao resultado.
PermissionRequestQuando um prompt de permissão é exibido.
NotificationQuando o agente o notifica.
SubagentStopQuando um subagente é concluído.
PreCompactAntes de a conversa ser compactada.
StopQuando um turno termina.
SessionEndQuando a sessão terminar.

Configure ganchos em qualquer arquivo de configurações:

{
"hooks": {
"PostToolUse": [
{ "matcher": "local_edit_file|local_write_file", "command": "npm run format --silent", "timeout": 30 }
],
"PreToolUse": [
{ "matcher": "local_bash", "command": "./scripts/check-command.sh" }
]
}
}
  • matcher é uma expressão regular no nome da ferramenta; omita-a para corresponder a todas as ferramentas.
  • O gancho recebe uma descrição em JSON do evento na entrada padrão.
  • Código de saída 2, ou saída em JSON com "decision": "block" e um reason, bloqueia a ação quando o evento permitir. additionalContext em JSON a saída adiciona texto para o modelo.
  • O tempo limite padrão é de 60 segundos, e o máximo é de 10 minutos.
  • Os ganchos são executados com seu ambiente, sem as credenciaisCHAMPREP.

Gerencie ganchos com /hooks, /hooks add EVENT [--matcher M] [--timeout S] [--scope user|project] -- COMMAND, /hooks disable ID, e /hooks enable ID.

ComandoOpções
/colorUma cor de destaque para as sessões deste projeto, para diferenciar sessões paralelas: blue, cyan, green, yellow, orange, red, pink, magenta, purple, gray, ou reset.
/themeauto, dark, light, high-contrast, ou colorblind. NO_COLOR e --no-color desativa as cores.
/statuslineSelecione trechos de profile, model, context, branch, mode, cost, e tasks; use /statusline command CMD para exibir a primeira linha da saída do seu próprio comando; /statusline reset restaura o padrão.
/output-styledefault, concise, explanatory, ou learning.
/vimEdição no estilo Vim no prompt.
/keybindingsVisualizar atalhos; /keybindings edit abre $CONFIG/ai/keybindings.json.
/configTudo o que foi mencionado acima em uma única tela.

As conversas do agente ficam armazenadas em sua CHAMPREP AIconta. Apenas o estado específico da máquina é armazenado localmente. Imprima todos os locais em sua máquina com:

Terminal window
champrep ai paths
O queOnde
CLI perfis e ambientes$CONFIG/config.toml
Suas configurações do agente: regras, modo, tema, linha de status, ganchos$CONFIG/ai/settings.json
Substituições de atalhos de teclado$CONFIG/ai/keybindings.json
Suas instruções pessoais$CONFIG/ai/CHAMPREP.md
Seus agentes, comandos e habilidades$CONFIG/ai/agents/, commands/, skills/
Seus servidores MCP locais$CONFIG/ai/mcp.json
Projetos confiáveis$CONFIG/ai/trusted-projects.json
Conversas recentes por diretório e listas de tarefas$STATE/ai/sessions.json
Histórico de prompts (ocultado e com limite de caracteres)$STATE/ai/history.jsonl
Logs de depuração (redigidos, mantidos por 7 dias)$STATE/ai/logs/
Pontos de verificação de arquivos$CACHE/ai/checkpoints/
Configurações do projeto (submetíveis ao commit).champrep/settings.json, mcp.json, agents/, commands/, skills/
Suas substituições de projeto (ignoradas pelo git).champrep/settings.local.json
Instruções do projetoCHAMPREP.md
Árvores de trabalho.champrep/worktrees/

As credenciais nunca são armazenadas nesses arquivos. Elas permanecem no keychain do sistema operacional.

RootmacOS e LinuxWindows
$CONFIG$XDG_CONFIG_HOME/champrep, caso contrário ~/.config/champrep%APPDATA%\champrep
$STATE$XDG_STATE_HOME/champrep, caso contrário ~/.local/state/champrep%LOCALAPPDATA%\champrep\state
$CACHE$XDG_CACHE_HOME/champrep, caso contrário ~/.cache/champrep%LOCALAPPDATA%\champrep\cache

Definir CHAMPREP_CONFIG_DIR para manter todos os três em um único diretório, em config/, state/, e cache/ subpastas. Isso é útil para instalações portáteis e execuções isoladas de CI.