graphql-api-architect
Projeta o adaptador GraphQL: schema, inputs e payloads, conexões, batch loads e mapa de erros.
31-graphql.md, bloco a bloco
O bank-app ainda não tem 31-graphql.md. Estes são os blocos que o SKILL.md diz que o parcial contém.
## 1 · Operations
One row per root field: kind, input port, return, REST counterpart
## 2 · Schema
Types, fields, nullability and why, the read model behind each
## 3 · Inputs and payloads
Input fields and shape validation, payload, userErrors codes
## 4 · Pagination
Per connection: directions, order with its unique key, default and maximum page, the cursor's keys
## 5 · Batch loads
Per child field: the batch port (a requirement when new), key, missing-key answer
## 6 · Project setup
Every limit with its value and reason — or inherited from UC-NNN — and the Admission rows: none, or the setup and this case's quota and cap (step 8b)
## 7 · Error map
Situation, where it lands, classification, errorCode
## 8 · Personal data
Per matching output field: form, receiver and reason
## 9 · Requirements to other partials
Batch ports, statements and indexes, access rows
## 10 · Contract test cases
Every case, by level
## 11 · Declared dependencies
The starter and its test starter
## 12 · Configuration
Every property, its value, its owner
## 13 · Deferred
Same shape as every partial. none when nothing was deferred
## Design patterns
Each pattern the controllers, records or mappers adopt — step 12b
O que lê, escreve e recusa
O contrato da própria skill, do SKILL.md, no texto original.
Class
design — the territory is skill_classes.design in @.claude/schemas/extensions.json, and ArchHook.java guard enforces it. Writes inside the use case folder and nothing else.
Reads
docs/use-cases/UC-NNN-<slug>/00-use-case.md (mandatory), 10-domain.md (mandatory), 30-rest.md (when present), the 31-graphql.md of earlier cases, pom.xml, the schema files under src/main/resources/graphql/, the active blueprint's packages.map, the Initializr's metadata, @.claude/rules/api-graphql.md, @.claude/rules/authorization.md, @.claude/rules/error-handling.md, @.claude/rules/personal-data.md, @.claude/rules/logging.md, @.claude/rules/naming.md, @.claude/rules/architecture-ddd.md, and this skill's references/ — plus, with an Admission row, @.claude/rules/inbound-admission.md and the partial that wrote the admission setup.
Writes
docs/use-cases/UC-NNN-<slug>/31-graphql.md. Nothing else.
Owns
the root fields and the port each calls, the schema's types and nullability, inputs, payloads and userErrors, connections and their ceilings, batch loads and the batch ports they ask for, the GraphQL error map, the personal-data decision per output field, the project's GraphQL setup, the GraphQL endpoint's quota and each root field's cap, and GraphQL dependencies and configuration.
Does not decide
the input ports, their read models or the exceptions (10-domain.md), the trigger or the Access row (00-use-case.md), the REST operations (30-rest.md), the access rule of each field and the filter chain (32-security.md), the batch statements and indexes (20-persistence.md), or the tests (40-tests.md). Does not write Java, schema files, pom.xml or application.yml — the executor does, from this partial. Doesn't touch .claude/rules/**.
Fonte: SKILL.md § Contract, no nerviz e4cae27.
O que o guard faz com ela
design é a classe da skill. O ArchHook abre uma fase quando a skill é chamada e confere cada escrita contra o território da classe. O texto à direita é o do próprio hook.
write_allow da classe design
- ✓
docs/use-cases/UC-*/** - ✓
docs/use-cases/BACKLOG.md src/**: migrations e classes são do executordocker-compose.yml: arquivo de outra classecaso de uso já aprovado: as specs ficam congeladas
A recusa sai com código 2 e a mensagem volta para o modelo.
PreToolUse Skill(graphql-api-architect) audit call exit 0 guard call exit 0 # a skill of another class replaces the phase # write_allow: docs/use-cases/UC-*/**, docs/use-cases/BACKLOG.md
PreToolUse Write(docs/use-cases/UC-005-record-kyc-verdict/31-graphql.md) guard write exit 0 PostToolUse audit file exit 0
PreToolUse Write(docker-compose.yml) guard write exit 2 ❌ `graphql-api-architect` is class `design` — docker-compose.yml is outside its territory. write_allow: docs/use-cases/UC-*/**, docs/use-cases/BACKLOG.md Put the content in the spec as a code block, or finish the run and invoke the skill that owns this path. If the path is legitimately this skill's, widen skill_classes.design in .claude/schemas/extensions.json — retrying will not help.
# UC-005-record-kyc-verdict-spec.md: status: approved PreToolUse Edit(docs/use-cases/UC-005-record-kyc-verdict/31-graphql.md) guard write exit 2 ❌ UC-005-record-kyc-verdict is approved — its specs are immutable. Record the change in the new use case's "Impact on approved use cases" section, and the one-line entry in UC-005-record-kyc-verdict/CHANGELOG.md, which stays writable.
Onde ela fica no trilho
Cada cartão é um passo do /new-feature; a seta leva o parcial que um passo entrega ao seguinte. Passos tracejados só rodam quando o caso de uso precisa.
/new-feature orchestrator · opus/new-feature-implement Quem lê o parcial depoisDepois da aprovação, o /new-feature-implement faz o executor construir o código. A spec é consolidada por referência e vale onde ela e um parcial divergem; o parcial é lido, por seção, para o detalhe.