# CLAUDE.md

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

## Project Overview

This is **设计人工智能：基础与应用** — a textbook project for design AI education. The book covers AI fundamentals (principles, perception, generation, agents) and their applications across design domains (digital media, industrial design, environmental design, urban planning).

A supplementary volume, **CC4SI (Claude Code for Spatial Intelligence)**, is preserved in `officefile/supplements/` and focuses on spatial intelligence and autonomous design using Claude Code.

**Key Characteristics:**
- Educational content organized as a book with 12 chapters + 9 appendices
- Mixed Chinese/English documentation and code
- Git-based workflow with Obsidian integration for content editing
- Pandoc-based export to Word (DOCX) with publisher template
- Standard research project directory structure

## Directory Structure

```
2026_DesignAI/
├── data/                              # Data and resources
│   ├── pics/                          # Book illustrations
│   └── references/                    # Bibliography data
├── dofile/                            # Code and scripts
│   └── examples/                      # Python code examples
│       ├── 00-introduction/           # Setup first assistant
│       ├── 01-foundations/            # State machines, modularity, etc.
│       └── 02-spatial-intelligence/   # Spatial analysis examples
├── officefile/                        # Main book content
│   ├── 00-frontmatter/                # 自序 (Preface), 目录 (TOC)
│   ├── 01-introduction/               # Ch1: AI development history
│   ├── 02-framework/                  # Ch2: AI theoretical framework
│   ├── 03-1d-sequence/                # Ch3: Sequence & text (RNN→LLM)
│   ├── 04-2d-vision/                  # Ch4: Images & vision (CNN)
│   ├── 05-3d-spatial/                 # Ch5: Spatial & 3D (PointNet)
│   ├── 06-reinforcement/              # Ch6: Reinforcement learning
│   ├── 07-generative-ai/              # Ch7: Generative AI (Diffusion)
│   ├── 08-agent/                      # Ch8: AI Agent
│   ├── 09-digital-media/              # Ch9: Digital media design
│   ├── 10-industrial-design/          # Ch10: Industrial design
│   ├── 11-environmental-landscape/    # Ch11: Environmental & landscape
│   ├── 12-urban-ecology/              # Ch12: Urban & ecological planning
│   ├── appendix/                      # Appendices 1-9
│   └── supplements/                   # CC4SI supplementary material
│       ├── 00-05/                     # Spatial intelligence chapters
│       └── appendix/                  # Academic writing workflow
├── output/                            # Generated outputs
│   └── docx/                          # Word exports
├── Archive/                           # Archived original directories
├── .claude/skills/markdown-to-docx/   # DOCX conversion skill
├── .pandoc/                           # Pandoc config (CSL, Zotero JSON)
└── .obsidian/                         # Obsidian vault configuration
```

## Book Structure

### Upper Volume: Principles & Technology

| Chapter | Topic | Lines | Status |
|---------|-------|-------|--------|
| 01 | AI development history & paradigm evolution | 367 | Complete |
| 02 | Theoretical framework (functional perspective, MLP) | 897 | Complete |
| 03 | 1D data: Sequence & text (RNN → LLM) | 1595 | Complete |
| 04 | 2D data: Images & vision (CNN → ViT) | 867 | Complete |
| 05 | 3D data: Spatial & 3D (PointNet → Spatial AI) | 1421 | Complete |
| 06 | Reinforcement learning (Q-Learning → RLHF) | 896 | Complete |
| 07 | Generative AI (VAE/GAN → Diffusion) | 496 | Complete |
| 08 | AI Agent (rules → LLM Agent) | 581 | Complete |

### Lower Volume: Design Applications

| Chapter | Topic | Lines | Status |
|---------|-------|-------|--------|
| 09 | Digital media design | 161 | Thin |
| 10 | Industrial & product design | 145 | Thin |
| 11 | Environmental & landscape design | 153 | Thin |
| 12 | Urban & ecological planning | 317 | Moderate |

### Appendices

9 appendices covering programming basics, Vibe Coding, academic writing, web tools, references, glossary, and tips.

## Working with This Repository

### For Content Editing
- Edit `.md` files in `officefile/` — they are the book source
- Use Obsidian for rich editing (vault at project root)
- Git commits follow conventional format: `docs(ch01): description`

### For DOCX Export
- Use the `markdown-to-docx` skill in `.claude/skills/`
- Publisher template: `machinery-industry-press-writing-template.dotx`
- Output goes to `output/docx/`

### For Python Examples
- Examples in `dofile/examples/` are self-contained
- Run directly: `python dofile/examples/01-foundations/state_machine.py`
- No global test suite — verify examples individually

## Language Considerations

- **Documentation**: Primarily Chinese with English technical terms
- **Code**: Variable names and comments in English
- **File names**: Mix of Chinese and English — use proper encoding

## Commit Convention

```
<type>(<scope>): <subject>

Types: feat, fix, docs, style, refactor, chore
Scopes: ch01-ch12, appendix, supplements, examples

Examples:
- docs(ch03): 补充 Transformer 注意力机制详解
- feat(examples): 新增空间推理示例
- fix(ch05): 修正 PointNet 结构描述
```