nerviz

↑ ↓ to move · Enter to open · Esc to closeTap a result

Architecture
skill · class design · opus

graphql-api-architect

Designs the GraphQL adapter: schema, inputs and payloads, connections, batch loads and the error map.

skill · designopuswrites 31-graphql.mdonly inside docs/use-cases/UC-*/**
§ the file it writes

31-graphql.md, block by block

bank-app has no 31-graphql.md yet. These are the blocks SKILL.md says the partial contains.

## 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

§ behavior

What it reads, writes and refuses

The skill's own contract, from SKILL.md, in the original wording.

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/**.

Source: SKILL.md § Contract, at nerviz e4cae27.

§ guard and hook

What the guard does with it

design is the skill's class. ArchHook opens a phase when the skill is called and checks every write against the class's territory. The text on the right is the hook's own.

write_allow of class design

  • ✓docs/use-cases/UC-*/**
  • ✓docs/use-cases/BACKLOG.md
  • src/**: migrations and classes are the executor's
  • docker-compose.yml: another class's file
  • a use case already approved: its specs are frozen

A refusal exits with code 2 and the message goes back to the model.

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
§ orchestration

Where it sits on the rail

Each card is a step of /new-feature; the arrow carries the partial one step hands to the next. Dashed steps run only when the use case needs them.

/new-feature orchestrator · opus
/new-feature-implement Who reads the partial next

After approval, /new-feature-implement has the executor build the code. The spec is consolidated by reference and wins where it and a partial disagree; the partial is read, by section, for detail.

31-graphql.mddocs/use-cases/UC-NNN-…/
read by section, for detail
java-spring-boot-developeragent · executor
writes the code
src/**designs one use case into a spec, writes no code
← back to the chains