test-repo/CLAUDE.md

# CLAUDE.md

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

## Project Overview

This is **Easy-Vibe**, an educational curriculum for learning AI Vibe Coding from zero to advanced levels. It's a documentation-based project using **VitePress** to serve educational content about AI-assisted software development.

The curriculum follows a progressive four-stage structure:

- **Stage 0 (幼儿园)**: Introduction to AI programming through games
- **Stage 1 (AI 产品经理)**: Building AI-powered web application prototypes
- **Stage 2 (初中级开发工程师)**: Full-stack development with databases and deployment
- **Stage 3 (高级开发工程师)**: Cross-platform development (WeChat mini-programs, Android apps, MCP)

## Development Commands

### Start Local Documentation Server

```bash
npm install      # Install dependencies (first time only)
npm run dev      # Start VitePress dev server
```

The documentation will be available at `http://localhost:5173` (VitePress default port)

### Build/Run Commands

- `npm run dev` - Start VitePress development server with hot reload
- `npm run build` - Build static site for production (outputs to `docs/.vitepress/dist`)
- `npm run preview` - Preview production build locally
- `npm run format` - Format code using Prettier

### Node Version Requirement

- Node.js >= 18.0.0 required (specified in package.json `engines`)

## Project Architecture

### Directory Structure

```
easy-vibe/
├── docs/                        # Main documentation content (served by VitePress)
│   ├── .vitepress/             # VitePress configuration and theme
│   │   ├── config.mjs          # Site configuration (nav, sidebar, plugins)
│   │   ├── theme/              # Custom theme extensions
│   │   │   ├── Layout.vue      # Override default layout with typewriter effect
│   │   │   ├── index.js        # Theme setup (Viewer.js, TypeIt, image optimization)
│   │   │   └── style.css       # Custom CSS overrides
│   │   ├── dist/               # Production build output (generated)
│   │   └── cache/              # VitePress cache (generated)
│   ├── index.md                # Homepage
│   ├── public/                 # Static assets (logo.png, etc.)
│   ├── assets/                 # Symlink to ../assets
│   ├── stage-0/                # Stage 0 content (幼儿园)
│   ├── stage-1/                # Stage 1 content (AI 产品经理)
│   ├── stage-2/                # Stage 2 content (初中级开发工程师)
│   ├── stage-3/                # Stage 3 content (高级开发工程师)
│   ├── appendix/               # Reference materials (AI capability dictionary)
│   ├── examples/               # Practical examples and tutorials (legacy)
│   ├── extra/                  # Additional knowledge (Git, API, RAG, etc.)
│   ├── guide/                  # Course guide
│   └── project/                # Legacy project documentation
├── assets/                     # Images and static assets
├── package.json                # Project dependencies and scripts
├── vercel.json                 # Vercel deployment configuration
└── README.md                   # Project overview and contribution guide
```

### Content Organization

Each stage follows a numbered chapter structure:

```
stage-{N}/
└── {category or chapter-dir}/
    └── index.md          # Main content file (or .md file directly)
```

Examples:
- `stage-1/1.1-introduction-to-ai-ide/index.md`
- `stage-2/backend/2.1-what-is-api/extra2/extra2-what-is-api.md`

**Note**: Content files may use either `index.md` or direct `.md` files depending on the chapter structure.

### Documentation System (VitePress)

The project uses **VitePress 2.0.0-alpha.15** with these key features:

**Configuration** (`docs/.vitepress/config.mjs`):
- **Single Sidebar**: Route-based sidebars configured per path prefix (`/stage-0/`, `/stage-1/`, etc.)
- **Navigation**: Top nav with links to each stage and appendix
- **Search**: Local search via `minisearch` (no external API required)
- **Dark Mode**: Built-in VitePress theme with toggle

**Custom Theme** (`docs/.vitepress/theme/`):
- **Image Viewer**: Viewer.js integration for zoom/rotate/flip on all images
- **Typewriter Effect**: TypeIt.js for homepage hero tagline animation
- **Image Optimization**: Automatic image height classes based on aspect ratio
- **Custom Layout**: Extends default theme with `Layout.vue` override

**Key Theme Behaviors**:
- Images with aspect ratio > 1.2 get height-limited classes (tall/very-tall/ultra-tall)
- Viewer.js initialized on `.vp-doc` container on each route change
- Typewriter effect only activates on homepage when `frontmatter.hero.tagline` is an array

### Sidebar Management

The sidebar is defined in `docs/.vitepress/config.mjs`. When adding new chapters:

1. Locate the appropriate route prefix section (`/stage-0/`, `/stage-1/`, etc.)
2. Add a new object with `text` (display name) and `link` (relative path)
3. For nested items, use `items` array with `collapsed: true|false`
4. **Links should not include `.md` extension** - VitePress handles this
5. Links should not include `index` - use directory path with trailing slash

Example pattern:
```javascript
{
  text: 'Chapter Title',
  link: '/stage-1/chapter-directory/'  // Note: trailing slash, no .md
}
```

### Asset Management

- Root-level static assets are in `/assets/` at project root
- Public files (favicon, logo) go in `docs/public/`
- Images are referenced with relative paths from markdown file location
- VitePress serves `docs/assets` as symlink to `../assets`
- Image optimization is automatic via theme (height-limited classes based on aspect ratio)

### Deployment

**Vercel** (vercel.json):
- Build command: `npm run build`
- Output directory: `docs/.vitepress/dist`
- Framework: vitepress

**Preview Production Build**:
```bash
npm run build
npm run preview  # Preview built site locally
```

### Legacy Content Structure

The project maintains three legacy sections for backward compatibility:

1. **Project 文档** (`project/`): Older chapter-based tutorials (migrated to Stage 2)
2. **Extra 扩展知识** (`extra/`): Supplementary topics - Git, APIs, RAG, deployment (migrated to Stage 2/3)
3. **Examples 实战案例** (`examples/`): Practical tutorials (migrated to Stage 0/3)

When updating content, prefer integrating into the stage structure over adding to legacy sections.

## Content Guidelines

### Writing New Chapters

1. Create directory: `docs/stage-{N}/{chapter-directory}/`
2. Create `index.md` or direct `.md` file with chapter content
3. Update `docs/.vitepress/config.mjs` sidebar with the new entry
4. Follow Chinese language conventions (this is a Chinese curriculum)

### Content Status Markers

In README.md, use these status indicators:

- ✅ Completed
- 🚧 In progress/Under construction

### File Naming Conventions

- Use kebab-case for directories: `1.1-introduction-to-ai-ide`, `frontend`, `backend`
- Content can be either `index.md` in a directory or a direct `.md` file
- Images use descriptive names; can be in chapter subdirectories or root `/assets/`

## Permissions

The project has configured bash permissions in `.claude/settings.local.json`:

- File operations: `which`, `find`, `mv`, `tree`, `cat`, `curl`, `lsof`, `mkdir`, `cp`, `ls`
- Process management: `xargs ps`, `kill`
- Development: `npm run dev`

## Key Context for Development

- **Educational Focus**: This is curriculum content, not application code
- **Target Audience**: Beginners to advanced developers learning AI-assisted programming
- **Language**: Primary content is in Chinese
- **Build Pipeline**: VitePress requires build step for production (`npm run build`)
- **Git Workflow**: Content changes should preserve formatting and structure
- **Asset Paths**: Always use relative paths from markdown file location

When making changes:

- Preserve the VitePress configuration in `docs/.vitepress/config.mjs`
- Maintain sidebar structure consistency in config.mjs
- Test locally with `npm run dev` before committing
- Check that image links work correctly
- Ensure theme customizations in `.vitepress/theme/` are not broken
- Run `npm run format` before committing code changes (uses Prettier: no semicolons, single quotes)