Skip to content

Commit ee862e2

Browse files
oalanicolasclaude
oalanicolas
and
claude
committed
docs: add CLI First architectural premise to README and CLAUDE.md
- Add "Premissa Arquitetural: CLI First" section to README.md - Create comprehensive .claude/CLAUDE.md (v3.0) with: - CLI First > Observability Second > UI Third hierarchy - Agent system documentation with personas and codebase mapping - Story-driven development workflow - Code standards (naming, imports, TypeScript, error handling) - Testing & quality gates - Git conventions - Claude Code optimization guidelines - Common commands reference Co-Authored-By: Claude (claude-opus-4-5-alan) <noreply@anthropic.com>
1 parent 4471a05 commit ee862e2

2 files changed

Lines changed: 304 additions & 0 deletions

File tree

‎.claude/CLAUDE.md‎

Lines changed: 281 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,281 @@
1+
# CLAUDE.md - Synkra AIOS
2+
3+
Este arquivo configura o comportamento do Claude Code ao trabalhar neste repositório.
4+
5+
---
6+
7+
## Premissa Arquitetural: CLI First
8+
9+
O Synkra AIOS segue uma hierarquia clara de prioridades que deve guiar **TODAS** as decisões:
10+
11+
```
12+
CLI First → Observability Second → UI Third
13+
```
14+
15+
| Camada | Prioridade | Descrição |
16+
|--------|------------|-----------|
17+
| **CLI** | Máxima | Onde a inteligência vive. Toda execução, decisões e automação. |
18+
| **Observability** | Secundária | Observar e monitorar o que acontece no CLI em tempo real. |
19+
| **UI** | Terciária | Gestão pontual e visualizações quando necessário. |
20+
21+
### Princípios Derivados
22+
23+
1. **A CLI é a fonte da verdade** - Dashboards apenas observam, nunca controlam
24+
2. **Funcionalidades novas devem funcionar 100% via CLI** antes de ter qualquer UI
25+
3. **A UI nunca deve ser requisito** para operação do sistema
26+
4. **Observabilidade serve para entender** o que o CLI está fazendo, não para controlá-lo
27+
5. **Ao decidir onde implementar algo**, sempre prefira CLI > Observability > UI
28+
29+
---
30+
31+
## Estrutura do Projeto
32+
33+
```
34+
aios-core/
35+
├── .aios-core/ # Core do framework
36+
│ ├── core/ # Módulos principais (orchestration, memory, etc.)
37+
│ ├── development/ # Agents, tasks, templates, checklists
38+
│ └── scripts/ # Utilitários e scripts
39+
├── apps/
40+
│ └── dashboard/ # Dashboard Next.js (Observability + UI)
41+
├── bin/ # CLI executables (aios-init.js, aios.js)
42+
├── src/ # Source code
43+
├── docs/ # Documentação
44+
│ └── stories/ # Development stories (active/, completed/)
45+
├── squads/ # Expansion packs
46+
├── packages/ # Shared packages
47+
└── tests/ # Testes
48+
```
49+
50+
---
51+
52+
## Sistema de Agentes
53+
54+
### Ativação de Agentes
55+
Use `@agent-name` ou `/AIOS:agents:agent-name`:
56+
57+
| Agente | Persona | Escopo Principal |
58+
|--------|---------|------------------|
59+
| `@dev` | Dex | Implementação de código |
60+
| `@qa` | Quinn | Testes e qualidade |
61+
| `@architect` | Aria | Arquitetura e design técnico |
62+
| `@pm` | Morgan | Product Management |
63+
| `@po` | Pax | Product Owner, stories/epics |
64+
| `@sm` | River | Scrum Master |
65+
| `@analyst` | Alex | Pesquisa e análise |
66+
| `@data-engineer` | Dara | Database design |
67+
| `@ux-design-expert` | Uma | UX/UI design |
68+
| `@devops` | Gage | CI/CD, git push (EXCLUSIVO) |
69+
70+
### Comandos de Agentes
71+
Use prefixo `*` para comandos:
72+
- `*help` - Mostrar comandos disponíveis
73+
- `*create-story` - Criar story de desenvolvimento
74+
- `*task {name}` - Executar task específica
75+
- `*exit` - Sair do modo agente
76+
77+
### Mapeamento Agente → Codebase
78+
79+
| Agente | Diretórios Principais |
80+
|--------|----------------------|
81+
| `@dev` | `src/`, `packages/`, `.aios-core/core/` |
82+
| `@architect` | `docs/architecture/`, system design |
83+
| `@data-engineer` | `packages/db/`, migrations, schema |
84+
| `@qa` | `tests/`, `*.test.js`, quality gates |
85+
| `@po` | `docs/stories/`, epics, requirements |
86+
| `@devops` | `.github/`, CI/CD, git operations |
87+
88+
---
89+
90+
## Story-Driven Development
91+
92+
1. **Trabalhe a partir de stories** - Todo desenvolvimento começa com uma story em `docs/stories/`
93+
2. **Atualize progresso** - Marque checkboxes conforme completa: `[ ]` → `[x]`
94+
3. **Rastreie mudanças** - Mantenha a seção File List na story
95+
4. **Siga critérios** - Implemente exatamente o que os acceptance criteria especificam
96+
97+
### Workflow de Story
98+
```
99+
@po *create-story → @dev implementa → @qa testa → @devops push
100+
```
101+
102+
---
103+
104+
## Padrões de Código
105+
106+
### Convenções de Nomenclatura
107+
108+
| Tipo | Convenção | Exemplo |
109+
|------|-----------|---------|
110+
| Componentes | PascalCase | `WorkflowList` |
111+
| Hooks | prefixo `use` | `useWorkflowOperations` |
112+
| Arquivos | kebab-case | `workflow-list.tsx` |
113+
| Constantes | SCREAMING_SNAKE_CASE | `MAX_RETRIES` |
114+
| Interfaces | PascalCase + sufixo | `WorkflowListProps` |
115+
116+
### Imports
117+
**Sempre use imports absolutos.** Nunca use imports relativos.
118+
```typescript
119+
// ✓ Correto
120+
import { useStore } from '@/stores/feature/store'
121+
122+
// ✗ Errado
123+
import { useStore } from '../../../stores/feature/store'
124+
```
125+
126+
**Ordem de imports:**
127+
1. React/core libraries
128+
2. External libraries
129+
3. UI components
130+
4. Utilities
131+
5. Stores
132+
6. Feature imports
133+
7. CSS imports
134+
135+
### TypeScript
136+
- Sem `any` - Use tipos apropriados ou `unknown` com type guards
137+
- Sempre defina interface de props para componentes
138+
- Use `as const` para objetos/arrays constantes
139+
- Tipos de ref explícitos: `useRef<HTMLDivElement>(null)`
140+
141+
### Error Handling
142+
```typescript
143+
try {
144+
// Operation
145+
} catch (error) {
146+
logger.error(`Failed to ${operation}`, { error })
147+
throw new Error(`Failed to ${operation}: ${error instanceof Error ? error.message : 'Unknown'}`)
148+
}
149+
```
150+
151+
---
152+
153+
## Testes & Quality Gates
154+
155+
### Comandos de Teste
156+
```bash
157+
npm test # Rodar testes
158+
npm run test:coverage # Testes com cobertura
159+
npm run lint # ESLint
160+
npm run typecheck # TypeScript
161+
```
162+
163+
### Quality Gates (Pre-Push)
164+
Antes de push, todos os checks devem passar:
165+
```bash
166+
npm run lint # ESLint
167+
npm run typecheck # TypeScript
168+
npm test # Jest
169+
```
170+
171+
---
172+
173+
## Convenções Git
174+
175+
### Commits
176+
Seguir Conventional Commits:
177+
- `feat:` - Nova funcionalidade
178+
- `fix:` - Correção de bug
179+
- `docs:` - Documentação
180+
- `test:` - Testes
181+
- `chore:` - Manutenção
182+
- `refactor:` - Refatoração
183+
184+
**Referencie story ID:** `feat: implement feature [Story 2.1]`
185+
186+
### Branches
187+
- `main` - Branch principal
188+
- `feat/*` - Features
189+
- `fix/*` - Correções
190+
- `docs/*` - Documentação
191+
192+
### Push Authority
193+
**Apenas `@devops` pode fazer push para remote.**
194+
195+
---
196+
197+
## Otimização Claude Code
198+
199+
### Uso de Ferramentas
200+
| Tarefa | Use | Não Use |
201+
|--------|-----|---------|
202+
| Buscar conteúdo | `Grep` tool | `grep`/`rg` no bash |
203+
| Ler arquivos | `Read` tool | `cat`/`head`/`tail` |
204+
| Editar arquivos | `Edit` tool | `sed`/`awk` |
205+
| Buscar arquivos | `Glob` tool | `find` |
206+
| Operações complexas | `Task` tool | Múltiplos comandos manuais |
207+
208+
### Performance
209+
- Prefira chamadas de ferramentas em batch
210+
- Use execução paralela para operações independentes
211+
- Cache dados frequentemente acessados durante a sessão
212+
213+
### Gerenciamento de Sessão
214+
- Rastreie progresso da story durante a sessão
215+
- Atualize checkboxes imediatamente após completar tasks
216+
- Mantenha contexto da story atual sendo trabalhada
217+
- Salve estado importante antes de operações longas
218+
219+
### Recuperação de Erros
220+
- Sempre forneça sugestões de recuperação para falhas
221+
- Inclua contexto do erro em mensagens ao usuário
222+
- Sugira procedimentos de rollback quando apropriado
223+
- Documente quaisquer correções manuais necessárias
224+
225+
---
226+
227+
## Comandos Frequentes
228+
229+
### Desenvolvimento
230+
```bash
231+
npm run dev # Iniciar desenvolvimento
232+
npm test # Rodar testes
233+
npm run lint # Verificar estilo
234+
npm run typecheck # Verificar tipos
235+
npm run build # Build produção
236+
```
237+
238+
### AIOS
239+
```bash
240+
npx aios-core install # Instalar AIOS
241+
npx aios-core doctor # Diagnóstico do sistema
242+
npx aios-core info # Informações do sistema
243+
```
244+
245+
### Dashboard (apps/dashboard/)
246+
```bash
247+
cd apps/dashboard
248+
npm install
249+
npm run dev # Desenvolvimento
250+
npm run build # Build produção
251+
```
252+
253+
---
254+
255+
## MCP Usage
256+
257+
Ver `.claude/rules/mcp-usage.md` para regras detalhadas.
258+
259+
**Resumo:**
260+
- Preferir ferramentas nativas do Claude Code sobre MCP
261+
- MCP Docker Gateway apenas quando explicitamente necessário
262+
- `@devops` gerencia toda infraestrutura MCP
263+
264+
---
265+
266+
## Debug
267+
268+
### Habilitar Debug
269+
```bash
270+
export AIOS_DEBUG=true
271+
```
272+
273+
### Logs
274+
```bash
275+
tail -f .aios/logs/agent.log
276+
```
277+
278+
---
279+
280+
*Synkra AIOS Claude Code Configuration v3.0*
281+
*CLI First | Observability Second | UI Third*

‎README.md‎

Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -14,6 +14,29 @@ Framework de Desenvolvimento Auto-Modificável Alimentado por IA. Fundado em Des
1414

1515
## Visão Geral
1616

17+
### Premissa Arquitetural: CLI First
18+
19+
O Synkra AIOS segue uma hierarquia clara de prioridades:
20+
21+
```
22+
CLI First → Observability Second → UI Third
23+
```
24+
25+
| Camada | Prioridade | Foco | Exemplos |
26+
| ----------------- | ---------- | ----------------------------------------------------------------------------- | -------------------------------------------- |
27+
| **CLI** | Máxima | Onde a inteligência vive. Toda execução, decisões e automação acontecem aqui. | Agentes (`@dev`, `@qa`), workflows, comandos |
28+
| **Observability** | Secundária | Observar e monitorar o que acontece no CLI em tempo real. | Dashboard SSE, logs, métricas, timeline |
29+
| **UI** | Terciária | Gestão pontual e visualizações quando necessário. | Kanban, settings, story management |
30+
31+
**Princípios derivados:**
32+
33+
- A CLI é a fonte da verdade - dashboards apenas observam
34+
- Funcionalidades novas devem funcionar 100% via CLI antes de ter UI
35+
- A UI nunca deve ser requisito para operação do sistema
36+
- Observabilidade serve para entender o que o CLI está fazendo, não para controlá-lo
37+
38+
---
39+
1740
**As Duas Inovações Chave do Synkra AIOS:**
1841

1942
**1. Planejamento Agêntico:** Agentes dedicados (analyst, pm, architect) colaboram com você para criar documentos de PRD e Arquitetura detalhados e consistentes. Através de engenharia avançada de prompts e refinamento com human-in-the-loop, estes agentes de planejamento produzem especificações abrangentes que vão muito além da geração genérica de tarefas de IA.

0 commit comments

Comments
 (0)