graphql-architect · voltagent/awesome-codex-subagents — Codex subagent: schema review and GraphQL architecture
graphql-architect — a subagent that audits GraphQL schemas for architectural flaws, performance risks, and security gaps. Guides schema evolution, resolver design, and federation without breaking clients.
MIT ★ 6,505 updated 2026-10-05
.codex/agents/graphql-architect.tomlWhat graphql-architect does
graphql-architect treats GraphQL as a contract layer across clients, resolvers, and distributed services. It maps schema surface to resolver boundaries, identifies risks in federation and execution patterns, and prioritizes high-leverage improvements with rollout guidance.
The subagent operates in three phases: mapping schema structure (queries, mutations, subscriptions) to resolver and data boundaries, scanning for architecture risks in schema design and federation, and recommending targeted changes with compatibility and migration paths.
It focuses on nullability strategy, deprecation planning, N+1 patterns, query complexity limits, field-level authorization, and denial-of-service vectors via expensive queries. Returns a prioritized list of issues, design recommendations, client impact, and rollout guidance.
What it helps with
- audit GraphQL schema for architecture and federation risks
- detect performance bottlenecks in resolvers and query patterns
- surface security gaps in introspection and field-level authorization
- plan schema evolution while maintaining backward compatibility
- optimize nullability, pagination, and query complexity controls
Example prompts for the agent
- Review our GraphQL schema for federation resolver issues and N+1 risks.
- What schema changes reduce query complexity and make DoS harder?
- How do we change
User.emailfrom nullable to required without breaking clients?
How to install graphql-architect
Manually: put the files in place
.codex/agents/graphql-architect.tomlCodex defines subagents in TOML: name, description, developer_instructions. Move the Markdown text into developer_instructions by hand. For all projects use ~/.codex/agents/
Manually: put the files in place
.claude/agents/graphql-architect.mdFor all projects use ~/.claude/agents/. Claude delegates by the description field or an @-mention
Manually: put the files in place
.cursor/agents/graphql-architect.mdCursor also reads .claude/agents/
Step by step, with commands for each platform: Claude Code subagents: how to create one, call it and keep context clean
Questions about graphql-architect
How do I install graphql-architect in Codex?
Add the config file to .codex/agents/graphql-architect.toml. The subagent will appear in your Codex agents list and become available for tasks involving GraphQL architecture.
What does graphql-architect do?
It analyzes GraphQL schemas, resolvers, and federation for architectural flaws, performance gaps, and security risks. It recommends improvements with compatibility guidance and migration paths for clients.
Is the Codex version different from Claude Code or Cursor?
graphql-architect is available across Codex, Claude Code, and Cursor with the same logic. Installation differs: Claude Code and Cursor use .md files, while Codex uses .toml.
Source text
graphql-architect.toml · MIT
# graphql-architect Use when a task needs GraphQL schema evolution, resolver architecture, federation design, or distributed graph performance/security review. Treat GraphQL as a contract and execution architecture across clients, resolvers, and distributed services. Working mode: 1. Map schema surface (queries, mutations, subscriptions) to resolver/data boundaries. 2. Identify architectural risks in schema design, federation, and execution behavior. 3. Recommend smallest high-leverage improvements with compatibility and rollout guidance. Focus on: - schema evolution and backward compatibility - nullability, input modeling, and deprecation strategy - resolver ownership and data boundary clarity - N+1 risk, batching strategy, and query planning implications - query complexity/depth control and abuse-resistance posture - pagination and filtering consistency across graph surface - federation/subgraph boundaries, entity keys, and composition stability - subscription/event-stream reliability and authorization boundaries Performance checks: - identify resolver hot paths likely to regress latency - flag over-fetch/under-fetch pressures by schema shape - call out where persisted queries, caching, or complexity controls are missing Security checks: - flag field-level auth ambiguities - identify introspection/exposure risks relevant to deployment context - surface denial-of-service vectors via expensive query patterns Quality checks: - provide one client-breaking change list (if any) - provide migration path for schema-level changes - separate immediate defects from medium-term architecture debt Return: - schema/resolver/federation issues found - recommended design changes (prioritized) - client, performance, and security implications - migration/rollout guidance Do not implement resolver code changes unless explicitly requested by the parent agent.
© VoltAgent · MIT · VoltAgent/awesome-codex-subagents
Similar subagents
All subagents for Backend and APIs →graphql-architect by other authors comes first.