Sistema do Agente @dev

Versão: 1.0.0 Criado: 2026-02-04 Owner: @dev (Dex - The Builder) Status: Documentação Oficial

Visão Geral

O agente @dev (Dex) e o Full Stack Developer do AIOX, responsavel pela implementacao de stories, debugging, refactoring e aplicacao das melhores praticas de desenvolvimento. Este agente atua como um Builder que implementa stories de forma precisa, atualiza somente as secoes autorizadas dos arquivos de story e mantem testes abrangentes.

Caracteristicas Principais

Caracteristica	Descrição
Persona	Dex - The Builder
Arquetipo	Builder / Aquario
Tom	Pragmatico, conciso, orientado a solucoes
Foco	Implementacao de stories, testes, qualidade de codigo
Fechamento	"-- Dex, sempre construindo"

Vocabulario Caracteristico

Construir
Implementar
Refatorar
Resolver
Otimizar
Debugar
Testar

Lista Completa de Arquivos

Arquivos Core de Tasks do @dev

Arquivo	Comando	Propósito
`.aiox-core/development/tasks/dev-develop-story.md`	`*develop {story-id}`	Task principal - desenvolve story completa com modos YOLO/Interactive/Pre-flight
`.aiox-core/development/tasks/dev-improve-code-quality.md`	`*improve-code-quality <path>`	Melhora qualidade do codigo (formatting, linting, modern-syntax)
`.aiox-core/development/tasks/dev-optimize-performance.md`	`*optimize-performance <path>`	Analisa e otimiza performance do codigo
`.aiox-core/development/tasks/dev-suggest-refactoring.md`	`*suggest-refactoring <path>`	Sugere oportunidades de refactoring automatizado
`.aiox-core/development/tasks/dev-backlog-debt.md`	`*backlog-debt`	Registra divida tecnica no backlog
`.aiox-core/development/tasks/apply-qa-fixes.md`	`*apply-qa-fixes`	Aplica correcoes baseadas em feedback de QA
`.aiox-core/development/tasks/execute-checklist.md`	`*execute-checklist`	Valida documentacao usando checklists
`.aiox-core/development/tasks/validate-next-story.md`	`*validate-story-draft`	Valida qualidade e completude de stories
`.aiox-core/development/tasks/sync-documentation.md`	`*sync-documentation`	Sincroniza documentacao com mudancas de codigo
`.aiox-core/development/tasks/po-manage-story-backlog.md`	(usado internamente)	Gerencia backlog de stories

Arquivos de Definição do Agente

Arquivo	Propósito
`.aiox-core/development/agents/dev.md`	Definição core do agente @dev (persona, comandos, workflows)
`.claude/commands/AIOX/agents/dev.md`	Comando Claude Code para ativar @dev

Arquivos de Checklists Usados pelo @dev

Arquivo	Propósito
`.aiox-core/product/checklists/story-dod-checklist.md`	Definition of Done para stories
`.aiox-core/product/checklists/pre-push-checklist.md`	Checklist antes de push
`.aiox-core/product/checklists/change-checklist.md`	Validacao de mudancas

Arquivos Relacionados de Outros Agentes

Arquivo	Agente	Propósito
`.aiox-core/development/tasks/qa-backlog-add-followup.md`	@qa	QA adiciona follow-ups ao backlog
`.aiox-core/development/tasks/qa-review-story.md`	@qa	QA revisa implementacao do @dev
`.aiox-core/development/tasks/github-devops-pre-push-quality-gate.md`	@github-devops	Quality gate antes de push
`.aiox-core/development/tasks/sm-create-next-story.md`	@sm	Scrum Master cria stories para @dev

Arquivos de Workflows que Usam @dev

Arquivo	Propósito
`.aiox-core/development/workflows/brownfield-fullstack.yaml`	Workflow full-stack brownfield
`.aiox-core/development/workflows/brownfield-service.yaml`	Workflow de servico brownfield
`.aiox-core/development/workflows/brownfield-ui.yaml`	Workflow UI brownfield
`.aiox-core/development/workflows/greenfield-fullstack.yaml`	Workflow full-stack greenfield
`.aiox-core/development/workflows/greenfield-service.yaml`	Workflow de servico greenfield
`.aiox-core/development/workflows/greenfield-ui.yaml`	Workflow UI greenfield

Flowchart: Sistema Completo do @dev

flowchart TB
    subgraph ACTIVATION["ATIVACAO DO AGENTE"]
        A["@dev"] --> B["Unified Activation Pipeline<br/>(unified-activation-pipeline.js)"]
        B --> C["Carrega devLoadAlwaysFiles"]
        C --> D["Exibe Quick Commands"]
        D --> E["HALT - Aguarda Usuario"]
    end

    subgraph DEVELOPMENT["CICLO DE DESENVOLVIMENTO"]
        E --> F{"Comando Recebido"}

        F -->|"*develop {id}"| G["dev-develop-story.md"]
        F -->|"*run-tests"| H["Executa Testes"]
        F -->|"*apply-qa-fixes"| I["apply-qa-fixes.md"]
        F -->|"*backlog-debt"| J["dev-backlog-debt.md"]
        F -->|"*improve-code-quality"| K["dev-improve-code-quality.md"]
        F -->|"*optimize-performance"| L["dev-optimize-performance.md"]
        F -->|"*suggest-refactoring"| M["dev-suggest-refactoring.md"]
    end

    subgraph DEVELOP_STORY["TASK: develop-story"]
        G --> N{"Modo de Execucao?"}

        N -->|"YOLO"| O["Modo Autonomo<br/>(0-1 prompts)"]
        N -->|"Interactive"| P["Modo Interativo<br/>(5-10 prompts)"]
        N -->|"Pre-flight"| Q["Planejamento<br/>Upfront"]

        O --> R["Implementar Tasks"]
        P --> R
        Q --> R

        R --> S["Escrever Testes"]
        S --> T["Executar Validacoes"]
        T --> U{"Todos Passam?"}

        U -->|"Sim"| V["Marcar [x] Task"]
        U -->|"Nao"| W["Corrigir Issues"]
        W --> T

        V --> X["Atualizar File List"]
        X --> Y{"Mais Tasks?"}

        Y -->|"Sim"| R
        Y -->|"Nao"| Z["CodeRabbit Self-Healing"]
    end

    subgraph COMPLETION["FINALIZACAO"]
        Z --> AA{"CRITICAL Issues?"}
        AA -->|"Sim"| AB["Auto-fix<br/>(max 2 iteracoes)"]
        AB --> AA
        AA -->|"Nao"| AC["Execute story-dod-checklist"]
        AC --> AD["Set Status:<br/>Ready for Review"]
        AD --> AE["HALT"]
    end

    subgraph COLLABORATION["COLABORACAO"]
        AE --> AF["@github-devops<br/>(git push, PR)"]
        AE --> AG["@qa<br/>(Review)"]
        AG -->|"Issues"| I
    end

    style ACTIVATION fill:#e3f2fd
    style DEVELOPMENT fill:#e8f5e9
    style DEVELOP_STORY fill:#fff8e1
    style COMPLETION fill:#f3e5f5
    style COLLABORATION fill:#fce4ec

Diagrama de Modos de Execucao

stateDiagram-v2
    [*] --> ModeSelection: *develop {story-id} [mode]

    ModeSelection --> YOLO: mode=yolo
    ModeSelection --> Interactive: mode=interactive (default)
    ModeSelection --> PreFlight: mode=preflight

    state YOLO {
        Y1: Initialize Decision Logging
        Y2: Read All Tasks
        Y3: Autonomous Decisions
        Y4: Implement + Test
        Y5: Log Decisions to .ai/

        Y1 --> Y2
        Y2 --> Y3
        Y3 --> Y4
        Y4 --> Y5
    }

    state Interactive {
        I1: Story Analysis
        I2: Present Summary
        I3: Decision Checkpoints
        I4: Educational Explanations
        I5: User Confirmations

        I1 --> I2
        I2 --> I3
        I3 --> I4
        I4 --> I5
    }

    state PreFlight {
        P1: Identify Ambiguities
        P2: Generate Questionnaire
        P3: Collect All Answers
        P4: Create Execution Plan
        P5: Zero-Ambiguity Execute

        P1 --> P2
        P2 --> P3
        P3 --> P4
        P4 --> P5
    }

    YOLO --> Validation
    Interactive --> Validation
    PreFlight --> Validation

    state Validation {
        V1: Run Tests
        V2: Execute Linting
        V3: CodeRabbit Check
        V4: DOD Checklist
    }

    Validation --> [*]: Ready for Review

Fluxo de CodeRabbit Self-Healing

flowchart TB
    subgraph SELF_HEALING["CODERABBIT SELF-HEALING (Story 6.3.3)"]
        A["Tasks Completas"] --> B["Iniciar Self-Healing Loop"]
        B --> C["iteration = 0<br/>max = 2"]

        C --> D["Executar CodeRabbit CLI<br/>(wsl bash -c)"]
        D --> E["Parse Output"]
        E --> F{"CRITICAL Issues?"}

        F -->|"Nao"| G{"HIGH Issues?"}
        G -->|"Sim"| H["Documentar em Dev Notes"]
        G -->|"Nao"| I["PASSED"]
        H --> I

        F -->|"Sim"| J["Auto-fix CRITICAL"]
        J --> K["iteration++"]
        K --> L{"iteration < 2?"}

        L -->|"Sim"| D
        L -->|"Nao"| M["HALT - Manual Fix Required"]

        I --> N["Proceed to DOD Checklist"]
    end

    style I fill:#c8e6c9
    style M fill:#ffcdd2

Mapeamento de Comandos para Tasks

Comandos de Desenvolvimento

Comando	Task File	Operacao
`*develop {story-id}`	`dev-develop-story.md`	Implementa story completa
`*develop {story-id} yolo`	`dev-develop-story.md`	Modo autonomo (0-1 prompts)
`*develop {story-id} interactive`	`dev-develop-story.md`	Modo interativo (5-10 prompts)
`*develop {story-id} preflight`	`dev-develop-story.md`	Planejamento upfront
`*run-tests`	(inline)	Executa linting e testes

Comandos de Qualidade

Comando	Task File	Operacao
`*apply-qa-fixes`	`apply-qa-fixes.md`	Aplica correcoes de QA
`*improve-code-quality <path>`	`dev-improve-code-quality.md`	Melhora qualidade de codigo
`*optimize-performance <path>`	`dev-optimize-performance.md`	Otimiza performance
`*suggest-refactoring <path>`	`dev-suggest-refactoring.md`	Sugere refactoring

Comandos de Backlog e Documentação

Comando	Task File	Operacao
`*backlog-debt`	`dev-backlog-debt.md`	Registra divida tecnica
`*sync-documentation`	`sync-documentation.md`	Sincroniza documentacao
`*validate-story-draft`	`validate-next-story.md`	Valida draft de story

Comandos de Contexto e Sessao

Comando	Operacao
`*help`	Mostra todos os comandos disponiveis
`*explain`	Explica o que acabou de fazer
`*guide`	Mostra guia de uso completo
`*load-full {file}`	Carrega arquivo completo (bypass summary)
`*clear-cache`	Limpa cache de contexto
`*session-info`	Mostra detalhes da sessao
`*exit`	Sai do modo developer

Integracoes entre Agentes

Diagrama de Colaboracao

flowchart TB
    subgraph DEV_ECOSYSTEM["ECOSSISTEMA DO @dev"]
        DEV["@dev (Dex)"]
    end

    subgraph UPSTREAM["UPSTREAM - Fornece Stories"]
        SM["@sm (River)<br/>Scrum Master"]
        PO["@po (Pax)<br/>Product Owner"]
    end

    subgraph PEER["PEER - Colaboracao"]
        QA["@qa (Quinn)<br/>Quality Assurance"]
    end

    subgraph DOWNSTREAM["DOWNSTREAM - Recebe Output"]
        GHDEVOPS["@github-devops (Gage)<br/>Git Operations"]
    end

    SM -->|"Cria story<br/>*create-next-story"| DEV
    PO -->|"Valida story<br/>*validate-story-draft"| DEV

    DEV -->|"Implementa<br/>*develop"| QA
    QA -->|"Feedback<br/>*apply-qa-fixes"| DEV

    DEV -->|"Story Complete<br/>Ready for Review"| GHDEVOPS
    GHDEVOPS -->|"git push<br/>gh pr create"| REMOTE["GitHub Remote"]

    style DEV fill:#e8f5e9
    style SM fill:#e3f2fd
    style PO fill:#e3f2fd
    style QA fill:#fce4ec
    style GHDEVOPS fill:#fff3e0

Fluxo de Colaboracao

De	Para	Trigger	Acao
@sm	@dev	Story criada	@dev implementa story
@po	@dev	Story validada	@dev pode comecar implementacao
@dev	@qa	Story "Ready for Review"	@qa revisa implementacao
@qa	@dev	Feedback com issues	@dev aplica correcoes (*apply-qa-fixes)
@dev	@github-devops	Codigo completo	@github-devops faz push/PR

Restricoes de Git

O @dev tem operacoes Git limitadas:

Operacoes PERMITIDAS:

git add - Stage files
git commit - Commit local
git status - Check estado
git diff - Review mudancas
git log - Ver historico
git branch - List/create branches
git checkout - Switch branches
git merge - Merge local

Operacoes BLOQUEADAS (somente @github-devops):

git push
git push --force
gh pr create
gh pr merge

Configuracao

Arquivos de Configuracao Relevantes

Arquivo	Propósito
`.aiox-core/core-config.yaml`	Configuracao central (devStoryLocation, coderabbit, etc.)
`.aiox-core/development/scripts/unified-activation-pipeline.js`	Pipeline canonico de ativacao e greeting
`.aiox-core/scripts/decision-recorder.js`	Logging de decisoes (YOLO mode)

devLoadAlwaysFiles

Arquivos carregados automaticamente na ativacao do @dev (definidos em core-config.yaml):

Padroes de codigo do projeto
Estrutura de diretorios
Convencoes de nomenclatura

CodeRabbit Integration

coderabbit_integration:
  enabled: true
  installation_mode: wsl

  self_healing:
    enabled: true
    type: light
    max_iterations: 2
    timeout_minutes: 15
    severity_filter:
      - CRITICAL
    behavior:
      CRITICAL: auto_fix
      HIGH: document_only
      MEDIUM: ignore
      LOW: ignore

Decision Logging (YOLO Mode)

decision_logging:
  enabled: true
  log_location: ".ai/decision-log-{story-id}.md"
  tracked_information:
    - Autonomous decisions made
    - Files created/modified/deleted
    - Tests executed and results
    - Performance metrics
    - Git commit hash (for rollback)

Best Practices

Quando Usar o @dev

USE @dev para:

Implementar stories aprovadas
Aplicar correcoes de QA
Refatorar codigo existente
Otimizar performance
Registrar divida tecnica
Executar e validar testes

NAO USE @dev para:

Criar stories (use @sm)
Push para remote (use @github-devops)
Validar arquitetura (use @architect)
Gerenciar backlog (use @po)

Modos de Execucao

Modo	Quando Usar	Prompts
YOLO	Tasks simples, deterministicas	0-1
Interactive	Aprendizado, decisoes complexas	5-10
Pre-flight	Requisitos ambiguos, trabalho critico	Todos upfront

Atualizacao de Story Files

SOMENTE estas secoes podem ser editadas pelo @dev:

Task/Subtask checkboxes
Dev Agent Record section
Agent Model Used
Debug Log References
Completion Notes List
File List
Change Log
Status

NUNCA editar:

Story description
Acceptance Criteria
Dev Notes (somente adicionar, não modificar)
Testing sections (estrutura)

Ciclo de Desenvolvimento

Leia task completa antes de implementar
Implemente incrementalmente (task por task)
Escreva testes para cada task
Execute validacoes antes de marcar [x]
Atualize File List apos cada arquivo criado/modificado
Execute CodeRabbit antes de finalizar
Execute DOD Checklist no final
Set status para "Ready for Review"

Troubleshooting

Story não encontrada

Erro: Story file not found at docs/stories/{story-id}.md

Solucao:

Verificar se story-id esta correto
Checar se story existe em docs/stories/
Usar caminho completo se necessario

CodeRabbit não encontrado

Erro: coderabbit: command not found

Solucao:

Verificar instalacao WSL: wsl bash -c '~/.local/bin/coderabbit --version'
Verificar path em wsl_config.installation_path
Re-instalar CodeRabbit se necessario

Testes falhando

Erro: Tests failed - cannot mark task as complete

Solucao:

Analisar output de erros
Corrigir issues identificados
Re-executar testes
Somente marcar [x] quando todos passarem

Blocking conditions

O @dev deve HALT e perguntar ao usuario quando:

Dependencias não aprovadas sao necessarias
Requisitos ambiguos apos checar story
3 falhas consecutivas tentando implementar/corrigir
Configuracao faltando
Testes de regressao falhando

Referencias

Tasks do @dev

Checklists

Agente

dev.md

Workflows

Relacionados

BACKLOG-MANAGEMENT-SYSTEM.md

Resumo

Aspecto	Detalhes
Total de Arquivos Core	10 task files + 1 agent definition
Comandos Principais	15 comandos (develop, run-tests, *apply-qa-fixes, etc.)
Modos de Execucao	3 (YOLO, Interactive, Pre-flight)
Checklists Usados	3 (story-dod, pre-push, change)
Workflows Integrados	6 (brownfield + greenfield variants)
Agentes Colaboradores	4 (@sm, @po, @qa, @github-devops)
Operacoes Git Permitidas	8 (add, commit, status, diff, log, branch, checkout, merge)
Operacoes Git Bloqueadas	4 (push, push --force, gh pr create, gh pr merge)
CodeRabbit Self-Healing	Light mode (max 2 iteracoes, CRITICAL only)

Changelog

Data	Autor	Descrição
2026-02-04	@dev	Documento inicial criado

-- Dex, sempre construindo

FilesExpand file tree

dev-system.md

Latest commit

History

dev-system.md

File metadata and controls

Sistema do Agente @dev

Visão Geral

Caracteristicas Principais

Vocabulario Caracteristico

Lista Completa de Arquivos

Arquivos Core de Tasks do @dev

Arquivos de Definição do Agente

Arquivos de Checklists Usados pelo @dev

Arquivos Relacionados de Outros Agentes

Arquivos de Workflows que Usam @dev

Flowchart: Sistema Completo do @dev

Diagrama de Modos de Execucao

Fluxo de CodeRabbit Self-Healing

Mapeamento de Comandos para Tasks

Comandos de Desenvolvimento

Comandos de Qualidade

Comandos de Backlog e Documentação

Comandos de Contexto e Sessao

Integracoes entre Agentes

Diagrama de Colaboracao

Fluxo de Colaboracao

Restricoes de Git

Configuracao

Arquivos de Configuracao Relevantes

devLoadAlwaysFiles

CodeRabbit Integration

Decision Logging (YOLO Mode)

Best Practices

Quando Usar o @dev

Modos de Execucao

Atualizacao de Story Files

Ciclo de Desenvolvimento

Troubleshooting

Story não encontrada

CodeRabbit não encontrado

Testes falhando

Blocking conditions

Referencias

Tasks do @dev

Checklists

Agente

Workflows

Relacionados

Resumo

Changelog