# CLAUDE.md This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. ## Project Overview **"How to Talk to Claude"** is a comprehensive AI collaboration guide built with Astro + Starlight. The project is complete and legendary-status, containing 4 complete learning paths from beginner to advanced AI collaboration techniques. Development server runs at `http://localhost:4321`. ## Development Commands | Command | Purpose | |---------|---------| | `npm run dev` | Start development server (localhost:4321) | | `npm run build` | Build production site to ./dist/ | | `npm run preview` | Preview build locally | | `npm run astro` | Run Astro CLI commands | **No test commands** - this is a documentation site without a test suite. ## Architecture & Structure ### Technology Stack - **Astro 5.6.1** with Starlight documentation framework - **Starlight components** for rich interactive content (Cards, Tabs, Asides, Steps, etc.) - **Starlight Theme Obsidian** for modern design - **Starlight Site Graph** plugin for content visualization - **Custom CSS** in `src/styles/custom.css` ### Content Architecture All content files are **MDX format** (not Markdown) to support Starlight components: ``` src/content/docs/ ├── index.mdx # Homepage with 4 learning paths ├── beginners/ # 18 complete guides (tutorials, how-tos, explanations, reference) ├── intermediate/ # 27 complete guides (advanced partnerships, domain-specific) ├── advanced/ # 14 guides (MCP-powered connected AI ecosystems) └── ayfkm/ # 31 guides ("Are You Kidding Me" - consciousness-level AI) ``` ### Content Types (Diataxis Framework) 1. **Tutorials** - Step-by-step learning experiences 2. **How-To Guides** - Problem-solving focused 3. **Explanations** - Understanding-oriented theory 4. **Reference** - Quick lookup information ### Component System **Import pattern for all .mdx files:** ```jsx import { Card, CardGrid, LinkCard, Aside, Badge, Steps, Tabs, TabItem, Code, Icon } from '@astrojs/starlight/components'; ``` **Proven enhancement patterns:** - Opening `Aside` callouts for key insights - `CardGrid` for organizing multiple concepts - `Tabs` for before/after examples or alternatives - `Steps` for sequential processes - Markdown code blocks for conversation examples - `LinkCards` for enhanced navigation ## Content Standards ### Voice & Style - **Conversational and human-centered** - explain like talking to a friend - **Experience-driven** - focus on real collaboration, not theory - **Problem-focused** - address actual AI frustrations - **Inclusive** - work across different tech backgrounds - **Psychologically aware** - acknowledge emotional aspects of learning ### Content Guidelines - Avoid jargon unless necessary - Use conversational examples over formal templates - Include personal anecdotes and relatable analogies - Be honest about AI limitations - Every section provides actionable value - Target 600-800 lines for enhanced content pieces ## Navigation Structure The site uses **two-tier navigation** with collapsed sections organized by: - **Beginners** (Start here badge, always expanded) - **Intermediate** (collapsed by default) - **Advanced** (MCP-Powered badge, collapsed) - **AYFKM** (🧙‍♂️ badge, collapsed) All internal links use `/path/to/page/` format and are properly connected. ## Project Status **LEGENDARY COMPLETION ACHIEVED**: - All 4 learning paths are 100% complete - 93 total content pieces across all guides - ~20,000+ lines of professional AI collaboration content - Zero placeholder content remaining - All MDX syntax and component integration working perfectly This represents the most comprehensive AI collaboration guide ever created, spanning from basic conversations to consciousness-level AI partnership. ## Working with This Codebase When making changes: 1. **Always use .mdx format** for content files 2. **Import Starlight components** at the top of files when needed 3. **Follow the proven enhancement patterns** documented in PROJECT-CONTEXT.md 4. **Test locally** with `npm run dev` before making significant changes 5. **Respect the content voice and style** - conversational, experience-driven, inclusive 6. **Use the Diataxis framework** - each piece should clearly fit one of the four content types The project is complete and stable - focus on maintenance and refinement rather than major structural changes.