---
layout: raw-data.njk
---
# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Project Overview

This is a specialized documentation generation project that creates **The New Zealand API Standard** by querying and synthesizing content from the NZ API Guidelines database via MCP (Model Context Protocol). The project uses a GraphRAG (Graph Retrieval-Augmented Generation) approach with a Neo4j database containing 5,612 document nodes.

## Database Structure

The NZ API Guidelines are organized into three parts:
- **Part A** (700 nodes, 12.5%): Foundational concepts, definitions, principles
- **Part B** (1,715 nodes, 30.5%): Technical specifications, standards, security requirements
- **Part C** (3,197 nodes, 57%): Implementation guidance, procedures, patterns

All content includes DocRef citations in the format: `([DocRef](https://docref.digital.govt.nz/nz/dia-apis-part[x]/2022/en/#[id]))`

## MCP Server Configuration

The project uses an MCP server called `docref-graphrag` configured in [.mcp.json](.mcp.json/):
- Remote endpoint: `https://api-standard-re-draft.vercel.app/mcp`
- Accessed via: `npx -y mcp-remote https://api-standard-re-draft.vercel.app/mcp`

Pre-approved MCP tools (no user confirmation needed):
- `mcp__docref-graphrag__get_schema` - Get database schema
- `mcp__docref-graphrag__semantic_search` - General semantic search
- `mcp__docref-graphrag__semantic_search_filtered` - Search with tag/part filters
- `mcp__docref-graphrag__semantic_search_balanced` - Ensure coverage across all parts
- `mcp__docref-graphrag__semantic_search_cross_document` - Find related content across parts
- `mcp__docref-graphrag__semantic_search_with_context` - Search with hierarchical context
- `mcp__docref-graphrag__run_cypher_query` - Direct Cypher queries (must include LIMIT clause)

## Essential Content Tags

When querying the database, filter by these tags:
- `must-or-shall` - Mandatory requirements
- `should-or-may` - Recommended practices
- `good-practice` - Best practices and guidance
- `definition` / `definitions` - Term definitions
- `patterns` - Implementation patterns
- `reference-examples-apis` - Code examples and references

## Project Workflow

The project follows a three-phase approach detailed in [EXECUTION_PLAN.md](EXECUTION_PLAN/):

### Phase 1: Research (Save searches locally)
Execute systematic searches and save results to `research/` directory:
- `01_design.md` - API design principles and patterns (~5 searches)
- `02_development.md` - REST API, HTTP methods, error handling (~7 searches)
- `03_security.md` - OAuth, authentication, TLS, threats (~7 searches)
- `04_deployment.md` - Versioning, gateways, releases (~5 searches)
- `05_operations.md` - Management, governance, monitoring (~7 searches)
- `06_definitions.md` - All definition-tagged content (~100 results)
- `07_patterns.md` - Authentication patterns and examples (~100 results)
- `08_good_practices.md` - Good practice content by topic (~180 results)

**Critical**: Save ALL search results locally before drafting. This creates traceable provenance and avoids overwhelming the context window.

### Phase 2: Drafting (Load research files selectively)
Generate `nz-api-standard.md` section by section:
1. Read ONLY the relevant research file(s) for each section
2. Synthesize content with DocRef citations preserved
3. Apply requirement elevation criteria (SHOULD → MUST where appropriate)
4. Track all citations in `citations_tracker.md`

**Memory-efficient approach**: Never load all research at once. Work incrementally.

### Phase 3: Finalization
1. Compile appendices from pattern and example files
2. Cross-reference using citations tracker
3. Quality review against checklist in instructions
4. Verify formatting compliance

## Document Requirements

Target document structure (from [LLM_INSTRUCTIONS_NZ_API_STANDARD.md](LLM_INSTRUCTIONS_NZ_API_STANDARD/)):

### Formatting Rules
- **Headings**: Level 1 for title only; Level 3-4 for main sections; Level 1 for appendix titles
- **Lists**: Ordered lists preferred; only follow body paragraphs (never start sections with lists)
- **Citations**: Every statement must include DocRef citation - never omit or paraphrase
- **Language**: Use normative language (MUST, MUST NOT, SHOULD, SHOULD NOT, MAY)
- **No in-text numbering** (avoid 1.1, 2.3 format)

### Content Organization (Lifecycle-Based)
1. Title page and introduction
2. Definitions section
3. API Design Phase (resource modeling, OpenAPI/AsyncAPI)
4. API Development Phase (HTTP methods, error handling, testing)
5. API Security Phase (OAuth 2.0, authentication, TLS)
6. API Deployment Phase (versioning, backwards compatibility)
7. API Management & Operations Phase (catalogues, monitoring, rate limiting)
8. Appendices:
   - A: Authentication/Authorization Patterns
   - B: API Specification Examples
   - C: Error Handling Reference
   - D: Glossary
   - E: References and Standards

### Requirement Elevation Criteria
Evaluate 'should-or-may' content for elevation to mandatory (MUST) based on:
- Essential for security (e.g., OAuth 2.0 for production)
- Critical for interoperability (e.g., OpenAPI specification)
- Foundational best practice (e.g., API testing requirements)
- Already widely adopted as de facto standard

## Search Strategy Best Practices

### Start with Schema
Always begin by understanding the database structure:
```bash
claude mcp call docref-graphrag get_schema
```

### Iterative Querying
1. Start small (LIMIT 5-15) to understand results
2. Use filters (tags, parts) to narrow down
3. Expand incrementally based on findings
4. All Cypher queries MUST include LIMIT clause (max 100)

### Example Searches
```bash
# Find mandatory security requirements in Part B
claude mcp call docref-graphrag semantic_search_filtered \
  '{"query": "OAuth authentication authorization", "part": "B", "tags": ["must-or-shall"], "limit": 40}'

# Get definitions
claude mcp call docref-graphrag semantic_search_filtered \
  '{"query": "API terminology", "tags": ["definition"], "limit": 100}'

# Cross-document search
claude mcp call docref-graphrag semantic_search_cross_document \
  '{"query": "API versioning strategies", "limit": 30}'
```

## Quality Checklist

Before considering work complete, verify:
- [ ] Every section has content with DocRef citations
- [ ] Normative language is correct (MUST/MUST NOT vs SHOULD/MAY)
- [ ] No in-text section numbering
- [ ] Lists only follow body paragraphs
- [ ] Main headings at consistent level (3 or 4)
- [ ] All appendices complete with examples and patterns
- [ ] Cross-references work correctly
- [ ] Document flows logically through lifecycle phases
- [ ] Technical accuracy maintained from source material

## Key Principles

1. **Research First**: Complete comprehensive research phase before any drafting
2. **Preserve Citations**: Every DocRef citation must be preserved exactly as returned by MCP tools
3. **Work Incrementally**: One section at a time, loading only necessary research files
4. **Maintain Traceability**: Every requirement must trace back to saved research with DocRef
5. **Don't Overlook Good Practices**: Content tagged "good-practice" often contains essential guidance
6. **Document Elevations**: When elevating SHOULD → MUST, document the rationale

## Expected Output

**File**: `nz-api-standard.md`
**Length**: 10,000-15,000 words
**Citations**: 250-400+ DocRef citations
**Research Files**: 8 organized markdown files in `research/` directory