Code Documentation

Updates project documentation with clear, focused content.

Documentation Locations

This Repository Structure

• •CLAUDE.md - Instructions for Claude Code (project structure, commands, architecture)
• •README.md (root) - Project overview, quick start
• •src/README.md - BFF application documentation (architecture, setup, API endpoints)
• •src/backend/ - Backend code (Express, TypeScript)
• •src/frontend/ - Frontend code (React, TypeScript)
• •Code comments - Only when logic isn't self-evident

Location Decision Tree

1. •Claude Code instructions → CLAUDE.md
2. •Workspace-level commands and architecture → CLAUDE.md
3. •BFF application setup, API endpoints, development → src/README.md
4. •Backend/frontend-specific architecture → src/README.md (relevant section)
5. •Function/class behavior → Code comments (sparingly)

Writing Guidelines

Be Concise

Bad: "This function is responsible for the task of processing user input data by validating it and then transforming it into the appropriate format."

Good: "Validates and transforms user input."

Use Direct Language

• •Start with verbs for actions
• •Avoid "should", "would", "could"
• •Skip unnecessary context

Structure

For feature documentation:

## Feature Name

Brief description (1 sentence).

### Usage

Code example or command

### Parameters/Options

- `param` - Description

For architectural updates to CLAUDE.md:

## Section Name

Key points only:
- Fact 1
- Fact 2

Instructions

1. •

   Identify the change: What was added, modified, or needs documentation?

2. •

   Choose location: Use the decision tree above

3. •

   Read existing docs: Check current content to maintain consistency

4. •

   Update concisely:

   • •Add new sections or update existing ones
   • •Remove outdated information
   • •Keep formatting consistent
   • •One sentence when one sentence suffices
5. •

   Verify accuracy: Ensure technical details match implementation

Examples

Adding New API Endpoint

Location: src/README.md (update API Endpoints section)

### GET /api/users
Get all users.

**Response:**
\`\`\`json
[
  { "id": 1, "name": "User 1" }
]
\`\`\`

Documenting New Environment Variable

Location: src/README.md (update Setup section) or CLAUDE.md (if workspace-level)

- `RATE_LIMIT` - Max requests per minute (default: 60)

Adding Development Command

Location: CLAUDE.md (update Development Commands section)

### API (`src/backend/`):
- `yarn validate` - Run linting and type checking

What NOT to Document

• •Obvious code behavior
• •Implementation details better suited for code comments
• •Temporary fixes or TODOs
• •Information that duplicates existing docs