How We Document

Documentation is how we remember what we built and why. It's also how we give Claude Code (and future teammates) the context to help us effectively.

Core principle: Document for your future self who has forgotten everything.

Why Documentation Matters

Documentation Types

Project/
├── README.md          ← What is this, how to run it
├── CHANGELOG.md       ← What changed and when
├── docs/
│   ├── PRD.md        ← What we're building and why
│   └── ARCHITECTURE.md ← How the system works (optional)
└── src/
    └── [code with comments where needed]

README.md

The front door to your project. Someone should understand what this is within 30 seconds.

README Template

# Project Name

One-sentence description of what this does.

## Features

- Feature 1
- Feature 2
- Feature 3

## Tech Stack

- NextJS 14
- Supabase
- DataForSEO API

## Getting Started

### Prerequisites

- Node.js 18+
- Supabase account
- DataForSEO API credentials

### Installation

```bash
git clone https://github.com/your-org/project-name
cd project-name
npm install
cp .env.example .env.local
# Edit .env.local with your credentials
npm run dev

Open http://localhost:3000

Environment Variables

Usage

Brief explanation of how to use the main features.

Project Structure

src/
├── app/           # NextJS app router pages
├── components/    # React components
├── lib/           # Utility functions
└── types/         # TypeScript types

Development

npm run dev      # Start development server
npm run build    # Build for production
npm run lint     # Run linter

Deployment

Deployed via Railway. Push to main triggers auto-deploy.

Contributing

See CONTRIBUTING.md if you have one.

License

MIT

### README Best Practices

| Do | Don't |
|----|-------|
| Update when project changes | Let it get stale |
| Include all env vars | Assume people know |
| Provide copy-paste commands | Make people figure it out |
| Keep it current | Document aspirational features |

## CHANGELOG.md

Track what changed and when. Essential for debugging ("when did this break?") and communication ("what shipped this week?").

### Changelog Format

Use [Keep a Changelog](https://keepachangelog.com/) format:

```markdown
# Changelog

All notable changes to this project will be documented in this file.

## [Unreleased]

### Added
- Export results to CSV
- Progress indicator during clustering

### Changed
- Improved error messages for API failures

### Fixed
- Clustering timeout for large datasets

## [1.0.0] - 2024-01-15

### Added
- Initial release
- Keyword upload via CSV
- HDBSCAN clustering
- Results display with cluster labels
- DataForSEO integration for embeddings

## [0.1.0] - 2024-01-08

### Added
- Project setup
- Basic UI scaffolding
- Database schema

Changelog Categories

When to Update

• Before merging PR: Add entry for what the PR does
• On release: Move "Unreleased" items to new version section
• Keep it human-readable: Write for users, not commit logs

Providing Context for AI

Claude Code works better with context. Help it help you.

CLAUDE.md File

Create a CLAUDE.md file in your project root with project-specific context:

# Claude Context for [Project Name]

## Project Overview
This is a keyword clustering tool for SEO analysis. Users upload
keywords, we cluster them using HDBSCAN, and display results.

## Tech Stack
- NextJS 14 with App Router
- Supabase for database
- FastAPI for ML processing
- OpenAI for embeddings
- HDBSCAN for clustering

## Key Patterns

### API Routes
All API routes are in `src/app/api/`. We use NextJS route handlers.

### Database
We use Supabase. Schema is in `supabase/migrations/`.
Always use parameterized queries, never string concatenation.

### Components
UI components in `src/components/`. We use Shadcn UI.
Import from `@/components/ui/` for base components.

### Environment
All env vars are in `.env.local`. See `.env.example` for required vars.

## Common Tasks

### Adding a new API endpoint
1. Create file in `src/app/api/[name]/route.ts`
2. Export GET, POST, etc. functions
3. Add authentication check if needed

### Adding a new page
1. Create folder in `src/app/[name]/`
2. Add `page.tsx` for the component
3. Add to navigation if needed

## Things to Avoid
- Don't commit .env files
- Don't use `any` type
- Don't skip error handling on API calls
- Don't hardcode API URLs

## Current Focus
Working on export feature. See issue #45.

Inline Comments

Comment code when the "why" isn't obvious:

// Good: Explains why
// We reduce dimensions before clustering because HDBSCAN
// performs poorly in high-dimensional spaces (curse of dimensionality)
const reducedEmbeddings = await reduceDimensions(embeddings, 50);

// Bad: Explains what (obvious from code)
// Reduce dimensions to 50
const reducedEmbeddings = await reduceDimensions(embeddings, 50);

// Good: Explains non-obvious behavior
// DataForSEO returns inconsistent field names, normalize here
const normalizedResults = results.map(r => ({
  keyword: r.keyword || r.search_query,
  ...
}));

Code Documentation

Use JSDoc for functions when helpful:

/**
 * Clusters keywords using HDBSCAN algorithm.
 *
 * @param keywords - Array of keyword strings to cluster
 * @param options - Clustering configuration
 * @param options.minClusterSize - Minimum keywords per cluster (default: 5)
 * @param options.minSamples - HDBSCAN min_samples parameter (default: 3)
 * @returns Promise resolving to clustered results
 *
 * @example
 * const clusters = await clusterKeywords(
 *   ['seo tools', 'seo software', 'keyword research'],
 *   { minClusterSize: 3 }
 * );
 */
async function clusterKeywords(
  keywords: string[],
  options: ClusterOptions = {}
): Promise<ClusterResult[]> {
  // ...
}

Documentation Maintenance

When to Update

Documentation Review

Before shipping, check:

• README matches current reality
• CHANGELOG has entry for changes
• .env.example has all new vars
• CLAUDE.md reflects current patterns

Common Mistakes

Writing docs once and forgetting

Signs: README says "Coming soon" from 6 months ago.

Fix: Update docs as part of the PR that changes behavior.

Over-documenting obvious code

Signs: // increment counter by 1 next to counter++

Fix: Document the why, not the what. Good code is self-documenting for the "what."

Under-documenting surprising behavior

Signs: "Why does this API return null here?" — no comment explains.

Fix: If you had to think about why, document it.

Not providing AI context

Signs: Claude Code keeps making the same mistakes.

Fix: Create CLAUDE.md with project patterns and constraints.

Evaluation Checklist

Your documentation is working if:

• New teammate can set up project from README
• You can remember what you shipped from CHANGELOG
• Claude Code understands project patterns
• Comments explain surprising decisions
• Docs stay current with code

Your documentation needs work if:

• README doesn't match reality
• You don't know what shipped last month
• Claude Code keeps repeating mistakes
• Code has no context for weird parts
• "Docs" folder is empty or outdated

Quick Reference

Essential Files

Changelog Entry Template

### Added/Changed/Fixed
- Brief description (see #123)

Comment Triggers

Document when:

• Workaround for external bug
• Non-obvious performance optimization
• Business rule that affects logic
• "Magic numbers" with meaning
• Known limitations