# 验证Claude Code已安装
claude --version
# 预期输出：claude-code/x.x.x (或类似版本号)

graph TB
    subgraph "Claude Code 六层记忆架构"
        L1["第1层: 全局 ~/.claude/CLAUDE.md<br/>跨项目用户偏好"]
        L2["第2层: 项目根 ./CLAUDE.md<br/>项目级指令"]
        L3["第3层: 目录级 ./src/CLAUDE.md<br/>子目录特定规则"]
        L4["第4层: .claude/rules/*.md<br/>模块化规则文件"]
        L5["第5层: 会话记忆<br/>auto-memory自动摘要"]
        L6["第6层: 跨工具共享记忆<br/>AGENTS.md / GEMINI.md"]
    end

    L1 --> L2 --> L3
    L2 --> L4
    L3 --> L5
    L4 --> L5
    L5 --> L6

    style L1 fill:#e8f5e9
    style L2 fill:#e3f2fd
    style L3 fill:#fff3e0
    style L4 fill:#fce4ec
    style L5 fill:#f3e5f5
    style L6 fill:#e0f7fa

~/.claude/
├── CLAUDE.md              # 全局用户偏好（所有项目生效）
├── settings.json           # 全局权限与MCP配置
├── credentials.json        # 认证信息（不要手动编辑）
├── statsig/                # 遥测数据
├── projects/               # 每个项目的工作记忆
│   └── -home-user-myproject/
│       └── CLAUDE.md       # 项目特定会话记忆
├── skills/                 # 全局Skills
├── commands/               # 全局自定义命令
└── memory/                 # 跨会话记忆存储

# 创建或编辑全局CLAUDE.md
cat > ~/.claude/CLAUDE.md << 'EOF'
# Global Preferences

## Language & Style
- 默认使用中文回复，代码注释可用英文
- 回复简洁明了，避免冗长解释

## Code Style
- 使用TypeScript strict模式
- 优先函数式编程，避免不必要的class
- 变量命名用camelCase，文件名用kebab-case
- 所有函数必须有返回类型注解

## Testing
- 新功能必须包含单元测试
- 使用vitest作为测试框架
- 测试文件命名: *.test.ts

## Git
- commit message使用conventional commits格式
- 不要自动commit，只在明确要求时执行
- 不要自动git add
EOF

{
  "permissions": {
    "allow": [
      "Bash(npm test)",
      "Bash(npm run lint)",
      "Bash(npx tsc --noEmit)",
      "Read",
      "Glob",
      "Grep"
    ],
    "deny": [
      "Bash(rm -rf *)",
      "Bash(curl * | bash)",
      "Bash(npm publish)"
    ]
  },
  "autoCompact": true,
  "compactThreshold": 80000
}

# 进入你的项目目录
cd ~/my-project

# 使用Claude Code内置的/init命令生成CLAUDE.md
claude
# 在Claude Code交互界面中输入:
> /init

# MyProject - E-Commerce API

## 项目概述
Node.js + Fastify + PostgreSQL的电商后端API服务。
使用TypeScript严格模式，遵循分层架构。

## 技术栈
- Runtime: Node.js 22
- Framework: Fastify 5.x
- ORM: Drizzle ORM
- Database: PostgreSQL 16
- Testing: Vitest + Supertest

## 项目结构

## 常用命令
- `npm run dev` — 启动开发服务器（端口3000）
- `npm test` — 运行全部测试
- `npm run test:watch` — 监听模式运行测试
- `npm run db:migrate` — 执行数据库迁移
- `npm run db:seed` — 填充测试数据

## 编码约定
- 所有API路由必须有对应的schema验证
- Service层不直接依赖Fastify实例
- 错误处理使用AppError类，不要throw原生Error
- 数据库查询在repository层完成，service层不写SQL
- 日志使用Fastify内置logger，不用console.log

## 禁止事项
- 不要修改migrations目录中已有的迁移文件
- 不要在routes层写业务逻辑
- 不要引入新的ORM（统一使用Drizzle）

# 为数据库层提供额外上下文
cat > src/repositories/CLAUDE.md << 'EOF'
## Repository层规则
- 所有查询使用Drizzle query builder
- 复杂查询（JOIN超过3张表）必须写注释说明
- 分页查询统一使用paginate()工具函数
- 不要使用raw SQL，除非性能要求极高且有注释说明
- 每个Repository类必须有对应的interface
EOF

# 为测试目录提供上下文
cat > src/__tests__/CLAUDE.md << 'EOF'
## 测试规则
- 使用describe/it结构组织测试
- 每个测试文件对应一个源文件
- 测试数据使用factory函数生成，不要硬编码
- 集成测试使用testcontainers启动PostgreSQL
- Mock只在外部服务边界使用，不要mock内部模块
EOF

# 创建rules目录
mkdir -p .claude/rules

# API设计规则
cat > .claude/rules/api-design.md << 'EOF'
---
description: Rules for API endpoint design
globs: ["src/routes/**"]

All API endpoints must:
1. Define request/response schemas using TypeBox
2. Use proper HTTP status codes (201 for creation, 204 for deletion)
3. Include authentication middleware for protected routes
4. Return consistent error format: { error: string, code: string, details?: any }
5. Support pagination for list endpoints with ?page&limit query params
EOF

# 数据库规则
cat > .claude/rules/database.md << 'EOF'
---
description: Database and migration rules
globs: ["src/repositories/**", "drizzle/**"]

Database conventions:
- All tables must have: id (uuid), created_at, updated_at columns
- Use UUID v7 for primary keys
- Soft delete using deleted_at column, never hard delete
- Index all foreign key columns
- Migration files are immutable once merged to main
EOF

# 安全规则
cat > .claude/rules/security.md << 'EOF'
---
description: Security best practices
globs: ["src/**"]

Security requirements:
- Never log sensitive data (passwords, tokens, PII)
- Use parameterized queries only (Drizzle handles this)
- Validate all input at route layer
- Hash passwords with bcrypt (cost factor 12)
- JWT tokens expire in 15 minutes, refresh tokens in 7 days
EOF

---
description: 规则描述（必填）
globs: ["匹配的文件路径模式"]
---

# 查看自动记忆存储位置
ls ~/.claude/projects/

# 典型路径结构：
# ~/.claude/projects/-home-user-myproject/CLAUDE.md

# 在Claude Code会话中，使用/memory命令管理记忆
> /memory

# 查看当前项目记忆内容
# 你可以编辑、删除或添加记忆条目

# 编辑项目记忆
vim ~/.claude/projects/-home-user-myproject/CLAUDE.md

## 项目记忆 (Auto-generated + Manual)

### 已解决的问题
- 2026-05-20: Drizzle ORM的joins语法在v0.38有变化，使用db.select().from(a).leftJoin(b, eq(a.id, b.aId))
- 2026-05-22: Fastify 5的schema验证必须在route options中定义，不能单独.register

### 架构决策
- 选择Drizzle而非Prisma，因为更好的类型推断和性能
- 使用plugin模式组织路由，每个domain一个plugin

### 已知的坑
- PostgreSQL的JSONB查询需要显式类型转换
- testcontainers启动慢，CI中需要30秒预热

graph LR
    A[会话开始] --> B{上下文是否充足?}
    B -->|是| C[正常对话]
    B -->|否| D[自动压缩<br/>autoCompact]
    D --> E[保留关键信息<br/>丢弃历史细节]
    E --> C
    C --> F{任务完成?}
    F -->|否| B
    F -->|是| G[重要知识写入<br/>项目记忆]

    style D fill:#fff3e0
    style G fill:#e8f5e9

my-project/
├── CLAUDE.md          # Claude Code专用（最丰富）
├── AGENTS.md          # GitHub Copilot / Codex
├── .cursorrules       # Cursor（或.cursor/rules/）
├── GEMINI.md          # Gemini CLI
├── .windsurfrules     # Windsurf
└── .github/copilot-instructions.md  # GitHub Copilot另一种方式

# 方案1：符号链接（最简单）
ln -s CLAUDE.md AGENTS.md
ln -s CLAUDE.md .cursorrules

# 方案2：精简版（推荐）
# AGENTS.md只保留跨工具通用的部分
cat > AGENTS.md << 'EOF'
# Shared AI Instructions
> Full project instructions in CLAUDE.md

## Code Style
- TypeScript strict mode
- Functional style preferred
- camelCase for variables, kebab-case for files

## Testing
- Vitest for unit tests
- All new features require tests

## Architecture
- Layered: routes → services → repositories
- See CLAUDE.md for complete details
EOF

mkdir ~/shop-api && cd ~/shop-api
npm init -y
npm install fastify drizzle-orm pg
npm install -D typescript vitest @types/pg drizzle-kit

# 创建.claude目录结构
mkdir -p .claude/rules
mkdir -p src/routes
mkdir -p src/services
mkdir -p src/repositories
mkdir -p src/__tests__

claude
# 在交互界面中输入:
> /init
# Claude Code会自动分析package.json和项目结构

# ShopAPI - 电商后端服务

## 一句话概述
Fastify + Drizzle ORM + PostgreSQL的RESTful电商API。

## 开发命令
- `npm run dev` — 开发服务器 localhost:3000
- `npm test` — 运行所有测试
- `npm run db:push` — 推送schema到数据库
- `npm run db:studio` — 打开Drizzle Studio

## 架构
严格三层架构：Routes → Services → Repositories
- Routes：HTTP处理、请求验证、响应格式化
- Services：业务逻辑、事务编排
- Repositories：数据库CRUD、SQL查询

## 编码规范
- 所有async函数必须处理错误（try/catch或Result类型）
- Repository方法返回`Promise<T[]>`而非`Promise<any>`
- 禁止在Service层直接import数据库实例
- 路由使用Fastify plugin模式注册

## 禁止
- 不要生成mock数据文件到src/目录
- 不要引入class-validator（使用TypeBox）
- 不要在routes中写SQL

cat > .claude/routes-rules.md << 'RULES'
---
description: Route layer conventions
globs: ["src/routes/**"]
---

## Route Rules
- Every route file exports a FastifyPluginAsync
- Use shorthand methods: app.get(), app.post(), etc.
- Schema validation with TypeBox in route options
- Error responses use reply.code().send() pattern
- Group related routes in one file (e.g., users.ts has GET/POST/PUT/DELETE /users)
RULES

cat > .claude/testing-rules.md << 'RULES'
---
description: Testing conventions
globs: ["src/__tests__/**", "**/*.test.ts"]
---

## Test Rules
- Use describe/it structure with meaningful descriptions
- Integration tests start with "should" verbs
- Factory functions for test data in helpers/test-factories.ts
- Each test file is independent (no shared mutable state)
- Use beforeAll for database setup, afterAll for cleanup
RULES

# 启动Claude Code
claude

# 测试上下文加载
> 你知道这个项目的技术栈和架构吗？

# 预期：Claude Code会准确描述Fastify + Drizzle + PostgreSQL三层架构

# 测试规则生效
> 帮我在src/routes/products.ts创建一个GET /products路由

# 预期：生成的代码会遵循以下规则：
# 1. 使用FastifyPluginAsync导出
# 2. 包含TypeBox schema验证
# 3. 调用Service层而非直接查数据库
# 4. 使用app.get()简写形式

graph TD
    A[使用Claude Code开发] --> B{AI生成代码<br/>是否符合预期?}
    B -->|是| C[继续开发]
    B -->|否| D[分析偏差原因]
    D --> E{是CLAUDE.md<br/>缺少信息吗?}
    E -->|是| F[补充到CLAUDE.md<br/>或rules/]
    E -->|否| G{是规则不够<br/>具体吗?}
    G -->|是| H[细化规则描述<br/>添加示例]
    G -->|否| I[考虑是否需要<br/>会话记忆补充]
    F --> C
    H --> C
    I --> J[写入项目记忆<br/>~/.claude/projects/]
    J --> C

    style F fill:#e3f2fd
    style H fill:#fff3e0
    style J fill:#e8f5e9

.claude/
├── rules/                          # 模块化规则
│   ├── api-design.md               # API设计规则
│   ├── database.md                 # 数据库规则
│   ├── security.md                 # 安全规则
│   ├── routes-rules.md             # 路由层规则
│   └── testing-rules.md            # 测试规则
├── settings.json                   # 项目级权限配置
├── commands/                       # 自定义斜杠命令
│   └── debug.md                    # /debug 命令
└── skills/                         # 项目级Skills

~/.claude/
├── CLAUDE.md                       # 全局偏好
├── settings.json                   # 全局权限
├── projects/
│   └── -home-user-shop-api/
│       └── CLAUDE.md               # 项目会话记忆
└── skills/                         # 全局Skills

shop-api/
├── CLAUDE.md                       # 项目主指令
├── AGENTS.md                       # 跨工具共享
├── .claude/                        # Claude Code配置目录
├── src/
│   ├── CLAUDE.md                   # src级通用规则
│   ├── routes/
│   │   └── CLAUDE.md              # 路由层特定规则
│   ├── services/
│   │   └── CLAUDE.md              # 服务层特定规则
│   ├── repositories/
│   │   └── CLAUDE.md              # 仓储层特定规则
│   └── __tests__/
│       └── CLAUDE.md              # 测试规则
├── package.json
└── tsconfig.json

# ❌ 无效写法
写干净的代码，遵循最佳实践。

# ✅ 有效写法
- 所有函数必须有返回类型注解
- 函数体不超过30行，超过则拆分
- 错误使用AppError类，不要throw new Error()
- 禁止使用any类型

# ✅ 正确格式
---
description: Route conventions
globs: ["src/routes/**"]
---

# ❌ 错误格式（缺少---）
description: Route conventions
globs: ["src/routes/**"]