Data Schema & Debugging

GraphQL Schema Conventions

Claude Code operates most effectively when it follows a rigid, predictable data structure. By defining these conventions in the .claude/skills/graphql-schema/SKILL.md file, you ensure that every mutation and query generated by the agent adheres to your project's architectural standards.

Core Schema Standards

Claude is configured to follow these patterns by default when the GraphQL skill is active:

• Naming Conventions: Use camelCase for fields and arguments, and PascalCase for types and enums.
• Mutation Payloads: Every mutation should return a payload object (e.g., UpdateUserPayload) containing both the affected entity and a list of user-facing errors.
• Input Objects: Use explicit Input types for mutation arguments rather than flat scalars to ensure future extensibility.
• Strict Typing: Favor Enums over Strings for state-based fields to provide Claude with clear boundaries for valid data.

Example: Defining a Mutation Pattern

When Claude generates a new feature, it refers to the following template structure:

type Mutation {
  """
  Update a user profile. Follows standard payload pattern.
  """
  updateUser(input: UpdateUserInput!): UpdateUserPayload!
}

input UpdateUserInput {
  id: ID!
  email: String
  role: UserRole
}

type UpdateUserPayload {
  user: User
  errors: [UserError!]!
}

Debugging Protocols

Maintaining an LLM-driven codebase requires a systematic approach to debugging—both for the code itself and for the agent's internal logic. Claude Code utilizes a combination of automated hooks and evaluation scripts to diagnose issues.

The Skill Evaluation Engine

If Claude isn't applying the correct conventions (e.g., it's writing REST endpoints instead of GraphQL queries), you can debug its intent detection via the Skill Evaluation Engine (.claude/hooks/skill-eval.js).

This engine analyzes your prompt against skill-rules.json to determine which domain knowledge to activate. You can verify how Claude is "thinking" by checking its match scoring:

| Match Type | Description | Debugging Action | | :--- | :--- | :--- | | Keyword | Matches specific terms like mutation or schema. | Add missing terms to triggers.keywords. | | Path Pattern | Matches file extensions or directories (e.g., src/graphql/**). | Check glob patterns in skill-rules.json. | | Intent Match | Detects high-level goals like "Refactor the API". | Refine the regex patterns in triggers.keywordPatterns. |

Systematic Troubleshooting Steps

When an error is detected, Claude follows a prioritized debugging protocol:

1. Linter Verification: Claude runs configured ESLint rules immediately after an edit. If a lint error occurs, it is programmed to self-correct before presenting the change.
2. Hook-Driven Testing: Using the .claude/settings.json hooks, Claude automatically triggers relevant tests (e.g., jest path/to/changed-file.test.ts).
3. Log Analysis: If a process fails, use the /logs command (if configured via MCP) or provide Claude with the output of your debug console. It is trained to parse stack traces and map them back to specific schema definitions.

Debugging with the Ticket System

For persistent bugs or complex architectural misalignments, use the /ticket command. This links the debugging context directly to your issue tracker (Jira/Linear), allowing you to:

• Attach the error logs.
• Reference the specific GraphQL schema version.
• Track the agent's multiple attempts to resolve the issue.

# Example: Using the ticket agent to debug a schema mismatch
/ticket "Debug why the UserProfile query is missing the 'avatarUrl' field in the generated frontend component"