Skip to content

Commit 46c450c

Browse files
ludamadludamad
committed
feat(docs): Add CLAUDE.md to documentation
Introduce a new documentation file, CLAUDE.md, providing guidance for working with the Aztec Protocol Documentation. Update the .gitignore to ensure CLAUDE.md is tracked.
1 parent 8ffe6f0 commit 46c450c

2 files changed

Lines changed: 223 additions & 0 deletions

File tree

‎docs/.gitignore‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -27,3 +27,5 @@ yarn-error.log*
2727
/docs/developers/reference/smart_contract_reference/aztec-nr
2828
/docs/docs/protocol-specs/public-vm/gen
2929
test-results
30+
31+
!CLAUDE.md

‎docs/CLAUDE.md‎

Lines changed: 221 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,221 @@
1+
# CLAUDE.md
2+
3+
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
4+
5+
## Overview
6+
7+
You are working with the **Aztec Protocol Documentation** - a comprehensive documentation site built with Docusaurus 3 for a privacy-centric zkRollup solution for Ethereum. Your role includes both technical development tasks and ensuring all documentation meets quality standards for accuracy, clarity, and usability.
8+
9+
## Development Commands
10+
11+
### Essential Commands
12+
13+
- `yarn` - Install dependencies
14+
- `yarn dev` - Start development server with hot reload (remote/codespaces)
15+
- `yarn dev:local` - Start development server (localhost only)
16+
- `yarn build` - Build production site with full validation
17+
- `yarn build:with-specs` - Build with protocol specifications included
18+
- `yarn spellcheck` - Run spell checking with cspell
19+
- `yarn clean` - Clean build artifacts and processed docs
20+
21+
### Development Workflow
22+
23+
The documentation uses a **preprocessing system** that:
24+
25+
- Pulls code from source files using `#include_code` macros
26+
- Generates auto-documentation from TypeScript/JavaScript sources
27+
- Processes macros like `#include_aztec_version` and `#include_testnet_version`
28+
- Outputs to `processed-docs/` folder for production builds
29+
30+
For development:
31+
32+
- `yarn preprocess` - Run preprocessing once
33+
- `yarn preprocess:dev` - Watch mode for preprocessing
34+
- In development mode (`ENV=dev`), Docusaurus serves from `docs/` folder directly
35+
- For production builds, it serves from `processed-docs/`
36+
37+
## Documentation Architecture
38+
39+
### Key Directories
40+
41+
- `docs/` - Main documentation source files
42+
- `processed-docs/` - Generated docs for production builds
43+
- `versioned_docs/` - Version-specific documentation copies
44+
- `src/preprocess/` - Preprocessing scripts and macro handlers
45+
- `src/components/` - React components for documentation
46+
- `static/img/` - Static images and assets
47+
48+
### Content Structure
49+
50+
- **Developer Guides** (`/developers/`) - Getting started, tutorials, references
51+
- **Aztec Concepts** (`/aztec/`) - Core protocol concepts and architecture
52+
- **Protocol Specs** (`/protocol-specs/`) - Detailed technical specifications
53+
- **Network Guides** (`/the_aztec_network/`) - Node operation and network participation
54+
55+
### Versioning System
56+
57+
Uses Docusaurus versioning with:
58+
59+
- Current version defined in `versions.json` (currently `v1.2.0`)
60+
- `versioned_docs/version-X.X.X/` contains historical versions
61+
- Macros only work in source `docs/` folder, not in versioned copies
62+
63+
## Documentation Review Standards
64+
65+
## Primary Review Objectives
66+
67+
### 1. Grammar & Language
68+
69+
- Fix grammatical errors, typos, and punctuation issues
70+
- Ensure proper sentence structure and paragraph flow
71+
- Correct verb tense consistency (prefer present tense for instructions)
72+
- Fix subject-verb agreement and pronoun references
73+
74+
### 2. Tone & Voice
75+
76+
- Maintain a professional tone
77+
- Use second person "you" perspective for user guides, how-to guides, and tutorials
78+
- Use first person plural "we" perspective for conceptual pages, architectural overviews and explanations
79+
- Keep language inclusive and accessible
80+
- Favor concise, direct language
81+
- Avoid passive voice where possible
82+
- Avoid jargon unless necessary (and define it when used)
83+
- Be encouraging rather than prescriptive ("you can" vs "you must" where appropriate)
84+
85+
### 3. Conciseness
86+
87+
- Remove redundant information
88+
- Combine related short sentences
89+
- Replace wordy phrases with concise alternatives
90+
- Eliminate unnecessary qualifiers and filler words
91+
- Keep paragraphs focused on single concepts
92+
93+
## Technical Review Criteria
94+
95+
### 4. Accuracy & Completeness
96+
97+
- Verify all technical information is correct
98+
- Ensure no critical steps are missing in procedures
99+
- Check that all prerequisites are stated upfront
100+
- Validate command syntax and parameters
101+
- Confirm version numbers and compatibility information
102+
103+
### 5. Code & Examples
104+
105+
- Verify code blocks are syntactically correct
106+
- Ensure proper language tags for syntax highlighting
107+
- Check that examples are practical and runnable
108+
- Include expected output where relevant
109+
- Follow coding best practices for the language
110+
111+
### 6. Structure & Organization
112+
113+
- Confirm logical information flow (simple → complex)
114+
- Verify proper heading hierarchy (H1 → H2 → H3, etc.)
115+
- Ensure consistent use of lists (ordered vs unordered)
116+
- Check that related information is grouped together and that duplicate information is minimized
117+
- Validate all internal links and cross-references
118+
119+
### 7. User Experience
120+
121+
- Include clear action items and expected outcomes
122+
- Provide troubleshooting for common issues
123+
- Add helpful notes, warnings, and tips using appropriate formatting
124+
- Include "Next steps" or "Related topics" where appropriate
125+
126+
## Consistency Standards
127+
128+
### Terminology
129+
130+
Use these terms consistently throughout:
131+
132+
- **[Aztec Protocol]** - Always capitalize and use full name on first mention
133+
- **[PXE]** - Always capitalize and use full name (Private eXecution Environment) on first mention
134+
135+
### Formatting Conventions
136+
137+
- **Code terms**: Use `backticks` for inline code, commands, file names, and technical terms
138+
- **Emphasis**: Use _italics_ sparingly for emphasis
139+
- **File paths**: Always use forward slashes (e.g., `/usr/local/bin`)
140+
- **Placeholders**: Use `[PLACEHOLDER_NAME]` format in examples
141+
142+
### Standard Sections
143+
144+
Every guide should include:
145+
146+
1. **Title** - Clear, descriptive, and action-oriented
147+
2. **Overview** - Brief description of what the guide covers
148+
3. **Prerequisites** - Required knowledge, tools, or access
149+
4. **Steps/Content** - Main body with clear headings
150+
5. **Verification** - How to confirm successful completion
151+
6. **Troubleshooting** - Common issues and solutions (where applicable)
152+
7. **Next Steps** - Related guides or advanced topics
153+
154+
## Special Instructions
155+
156+
### Do Review For:
157+
158+
- ✅ Ambiguous instructions that could confuse users
159+
- ✅ Missing context or assumptions about user knowledge
160+
- ✅ Outdated screenshots or version references
161+
- ✅ Broken markdown formatting
162+
- ✅ Inconsistent capitalization in headings
163+
- ✅ Missing alt text for images
164+
- ✅ Security implications of commands or configurations
165+
166+
### Do NOT Change:
167+
168+
- ❌ Product-specific command names or parameters
169+
- ❌ Intentionally simplified examples for beginners
170+
- ❌ Legal disclaimers or license text
171+
- ❌ Direct quotes from external sources
172+
- ❌ API endpoint URLs or configuration values
173+
174+
## Review Output Format
175+
176+
When reviewing, provide feedback in this format:
177+
178+
1. **Summary**: Brief overview of the document's current state
179+
2. **Critical Issues**: Must-fix problems affecting accuracy or usability
180+
3. **Improvements**: Suggested enhancements for clarity and consistency
181+
4. **Positive Aspects**: What's working well (to maintain in future edits)
182+
183+
For inline edits, use clear markers:
184+
185+
- `[GRAMMAR]` - Grammar or spelling fix
186+
- `[CLARITY]` - Rewrite for better understanding
187+
- `[TECHNICAL]` - Technical accuracy correction
188+
- `[STYLE]` - Style guide compliance
189+
- `[STRUCTURE]` - Organization improvement
190+
191+
## Project-Specific Guidelines
192+
193+
### Domain Context
194+
195+
- **Industry**: Blockchain, Smart Contracts, Privacy, zero-knowledge, rollups on Ethereum
196+
- **Primary Users**: Smart contract developers, protocol engineers, protocol researchers
197+
- **Documentation Type**: Explainer docs, how-to guides, reference docs, API docs, tutorials
198+
199+
### Version Management
200+
201+
- Current version: see ./versions.json
202+
- Version notation format: **v1.2.1**
203+
204+
### External References
205+
206+
Approved external documentation sources:
207+
208+
- Noir: https://noir-lang.org/docs
209+
210+
---
211+
212+
## Notes for Claude
213+
214+
- Prioritize clarity and user success over strict style adherence
215+
- When in doubt, favor explicit over implicit information
216+
- Consider the user's journey through the entire documentation site
217+
- Flag any content that might need subject matter expert review
218+
- Suggest improvements even if they go beyond pure editing
219+
220+
Last updated: 2025-08-08
221+
Version: 1.0

0 commit comments

Comments
 (0)