AI 开发环境搭建：2026 年工具、配置与 Dotfiles 完全指南

# 通过原生安装器安装（推荐）
curl -fsSL https://cli.claude.ai/install.sh | sh

# 或通过 npm 安装（如果你更习惯包管理器）
npm install -g @anthropic-ai/claude-code

# 验证安装
claude --version

# 启动 Claude Code，按照提示完成认证
claude

# 或者直接认证
claude auth login

# CLAUDE.md

## 项目概览
- **技术栈**：Node.js / TypeScript / PostgreSQL / React
- **架构**：Monorepo，使用 packages/ 目录
- **Node 版本**：22（使用 nvm 管理）

## 常用命令
```bash
# 开发
npm run dev          # 启动开发服务器（端口 3000）
npm run test         # 运行测试
npm run test:watch   # 监听模式运行测试
npm run lint         # ESLint + Prettier 检查
npm run typecheck    # TypeScript 类型检查

# 数据库
npm run db:migrate   # 执行待运行的迁移
npm run db:seed      # 填充开发数据
npm run db:reset     # 重置并重新填充数据库
```

## 代码规范
- 使用函数式组件配合 Hooks（禁止使用 class 组件）
- 所有 API 路由放在 `src/routes/` 下，遵循 REST 规范
- 数据库查询使用 `src/repositories/` 中的 Repository 模式
- 错误处理统一使用 `src/utils/errors.ts` 中的 AppError 类
- 测试文件与源文件同目录放置（如 `user.service.test.ts`）

## 重要规则
- 绝对不要修改 `src/generated/` 下的文件——它们是自动生成的
- 提交前必须运行 `npm run typecheck`
- 数据库迁移必须可回滚
- API 响应必须遵循 `src/utils/response.ts` 中的格式

## 架构说明
- 认证：JWT + Refresh Token 轮换
- 文件上传：通过预签名 URL 存储到 S3（禁止本地存储）
- 后台任务：BullMQ + Redis
- 缓存：Redis，API 响应默认 5 分钟 TTL

{
  "mcpServers": {
    "context7": {
      "command": "npx",
      "args": ["-y", "@context7/mcp-server"],
      "description": "Library documentation lookup"
    },
    "postgres": {
      "command": "npx",
      "args": ["-y", "@anthropic/mcp-postgres"],
      "env": {
        "DATABASE_URL": "postgresql://user:pass@localhost:5432/mydb"
      },
      "description": "Direct database access"
    },
    "playwright": {
      "command": "npx",
      "args": ["-y", "@anthropic/mcp-playwright"],
      "description": "Browser automation for testing"
    }
  }
}

{
  "hooks": {
    "preCommit": {
      "command": "npm run lint && npm run typecheck",
      "description": "Run lint and type checks before any commit"
    },
    "postFileEdit": {
      "pattern": "*.test.ts",
      "command": "npm run test -- --related",
      "description": "Run related tests after editing test files"
    }
  }
}

{
  "cursor.agent.model": "claude-sonnet-4-20250514",
  "cursor.autocomplete.enabled": true,
  "cursor.chat.defaultModel": "claude-sonnet-4-20250514",
  "editor.fontSize": 14,
  "editor.minimap.enabled": false,
  "terminal.integrated.fontSize": 13
}

You are an expert TypeScript/React developer working on a production application.

## Code Style
- Use TypeScript strict mode
- Prefer named exports over default exports
- Use Zod for runtime validation
- Use React Query for server state management

## Project Structure
- Components: src/components/{feature}/{ComponentName}.tsx
- Hooks: src/hooks/use{HookName}.ts
- API routes: src/routes/{resource}.routes.ts

## Rules
- Never use `any` type — use `unknown` and narrow
- All API responses go through the response utility
- Components must have displayName for debugging
- Prefer composition over inheritance

# ~/.tmux.conf — AI 开发布局
# 前缀键
set -g prefix C-a
unbind C-b

# 创建 AI 开发布局
# Pane 0: Claude Code 会话
# Pane 1: 运行开发服务器
# Pane 2: Git 操作
bind-key A split-window -h \; \
  split-window -v \; \
  select-pane -t 0 \; \
  send-keys 'claude' C-m \; \
  select-pane -t 1 \; \
  send-keys 'npm run dev' C-m \; \
  select-pane -t 2

# 增大回滚缓冲区以容纳 AI 输出
set -g history-limit 50000

# 更好的复制模式，方便复制 AI 响应
setw -g mode-keys vi

// ~/.config/zellij/layouts/ai-dev.kdl
layout {
    pane split_direction="vertical" {
        pane size="60%" {
            command "claude"
            name "AI Agent"
        }
        pane split_direction="horizontal" {
            pane {
                command "npm"
                args "run" "dev"
                name "Dev Server"
            }
            pane {
                name "Git / Shell"
            }
        }
    }
}

# ===== AI 开发别名 =====

# Claude Code 快捷命令
alias cc="claude"
alias ccc="claude --continue"        # 继续上次对话
alias ccr="claude --resume"          # 恢复特定会话
alias ccp="claude --print"           # 单次模式（非交互式）
alias ccm="claude --model opus"      # 复杂任务用 Opus
alias ccs="claude --model sonnet"    # 快速任务用 Sonnet

# 常用 Claude Code 任务
alias ccplan="claude 'Read the codebase and create an implementation plan for:'"
alias cctest="claude 'Write comprehensive tests for the changes in the last commit'"
alias ccreview="claude 'Review the code changes in the current branch and suggest improvements'"
alias ccfix="claude 'Fix the failing tests and lint errors'"
alias ccdoc="claude 'Generate documentation for the public API in this project'"

# Git + AI 工作流
alias gaic="claude 'Create a well-formatted commit message for the staged changes and commit them'"
alias gapr="claude 'Create a pull request with a detailed description for the current branch'"

# 项目初始化
alias ainit="cp ~/.dotfiles/templates/CLAUDE.md . && cp ~/.dotfiles/templates/.cursorrules . && echo 'AI config files created'"

# 省钱模式
alias ccheap="claude --model haiku"  # 简单任务用 Haiku

# ~/.gitconfig AI 开发相关配置

[alias]
    # AI 辅助提交：暂存所有文件，让 AI 写提交信息
    aic = "!f() { git add -A && claude --print 'Write a concise commit message for these changes. Follow conventional commits format.' | git commit -F -; }; f"

    # 提交前用 AI 审查变更
    air = "!f() { git diff --staged | claude --print 'Review this diff. Are there any issues, bugs, or improvements?'; }; f"

    # 用 AI 生成分支描述
    aib = "!f() { git log main..HEAD --oneline | claude --print 'Summarize what this branch does based on the commit history'; }; f"

[commit]
    # 适用于 AI 辅助开发的提交模板
    template = ~/.gitmessage

[diff]
    # 更适合 AI 生成代码的 diff 算法
    algorithm = histogram

# <type>(<scope>): <description>
#
# 类型：feat, fix, refactor, test, docs, chore, perf
# 范围：可选，受影响的模块或区域
#
# 正文：解释"为什么"，而不是"做了什么"（diff 已经展示了"做了什么"）
#
# 脚注：BREAKING CHANGE, Closes #issue
#
# AI 辅助：标注哪些部分是 AI 生成的

你：我需要给 API 加一个限流系统。
    我们用的是 Express.js + Redis。

Claude Code：[阅读代码库，分析中间件链，
             提出基于滑动窗口算法的架构方案，
             找出所有需要保护的路由，
             建议限流追踪的数据库 Schema]

根据以下方案实现限流系统：
[粘贴 Claude Code 的架构方案]

先从 Redis 限流中间件开始。

你：给我们刚才添加的限流中间件写测试。
    覆盖以下边界情况：窗口过期、并发请求、
    Redis 连接中断。

## Python 环境
- Python 3.12+，通过 pyenv 管理
- 包管理器：uv（不是 pip）
- 虚拟环境：`.venv/`（由 uv 自动创建）

## 命令
```bash
uv run pytest              # 运行测试
uv run ruff check .        # 代码检查
uv run mypy src/           # 类型检查
uv run python -m src.main  # 运行应用
```

## 代码风格
- 所有函数签名必须有类型标注
- 数据验证使用 Pydantic v2
- 所有 I/O 操作使用异步函数
- 文档字符串使用 Google 格式

## Go 环境
- Go 1.23+
- Module：github.com/yourorg/yourproject

## 命令
```bash
go test ./...           # 运行所有测试
go vet ./...            # 静态分析
golangci-lint run       # 综合代码检查
go build -o bin/app .   # 构建二进制文件
```

## 规范
- 错误包装：fmt.Errorf("context: %w", err)
- 接口定义放在使用方的包中
- 使用表驱动测试
- 禁止使用 init() 函数

You are a senior developer working on a production {LANGUAGE} application.

## Response Style
- Be concise. No explanations unless asked.
- Show code changes as diffs when possible.
- If unsure about project conventions, check existing code first.

## Code Quality
- All code must pass the existing linter configuration
- Write tests for new functionality
- Prefer readability over cleverness
- Use existing utilities and helpers before creating new ones

## Architecture
- Follow existing patterns in the codebase
- New files go in the appropriate directory per the project structure
- Database changes require migrations (never modify schema directly)
- API changes require updating the OpenAPI spec

## Forbidden
- Do not use deprecated APIs or libraries
- Do not add new dependencies without explicit approval
- Do not modify CI/CD configuration files
- Do not change environment variable names

# ~/.zshrc 或 ~/.bashrc — AI 开发专区

# ===== Claude Code =====
alias cc="claude"
alias ccc="claude --continue"
alias ccr="claude --resume"
alias ccp="claude --print"
alias ccm="claude --model opus"
alias ccs="claude --model sonnet"

# ===== 常用任务 =====
alias ccplan="claude 'Read the codebase and create an implementation plan for:'"
alias cctest="claude 'Write comprehensive tests for the changes in the last commit'"
alias ccreview="claude 'Review the staged changes and suggest improvements'"
alias ccfix="claude 'Fix the failing tests and lint errors'"

# ===== Git + AI =====
alias gaic="claude 'Create a commit message for staged changes and commit'"
alias gapr="claude 'Create a PR description for the current branch'"

# ===== 会话管理 =====
alias ccls="claude sessions list"         # 列出最近会话
alias cclast="claude --resume last"       # 恢复最近一次会话

# ===== 项目初始化 =====
ainit() {
    echo "正在创建 AI 配置文件..."
    [ ! -f CLAUDE.md ] && cp ~/.dotfiles/templates/CLAUDE.md . && echo "  已创建 CLAUDE.md"
    [ ! -f .cursorrules ] && cp ~/.dotfiles/templates/.cursorrules . && echo "  已创建 .cursorrules"
    [ ! -d .claude ] && mkdir -p .claude && echo "  已创建 .claude/"
    echo "完成。请编辑文件以匹配你的项目。"
}

{
  "mcpServers": {
    "context7": {
      "command": "npx",
      "args": ["-y", "@context7/mcp-server"],
      "description": "Real-time library documentation"
    },
    "playwright": {
      "command": "npx",
      "args": ["-y", "@anthropic/mcp-playwright"],
      "description": "Browser automation and testing"
    },
    "memory": {
      "command": "npx",
      "args": ["-y", "@anthropic/mcp-memory"],
      "description": "Persistent memory across sessions"
    }
  }
}

# 启动新的 Claude Code 会话
claude

# 提供完整上下文
> 我需要给应用添加邮件通知功能。
> 用户应该能配置通知偏好。
> 技术栈是 Express.js、PostgreSQL 和 React。
> 请分析代码库，提出实现方案。

# 继续同一个 Claude Code 会话
> 审查一下这个方案的潜在问题：
> - 与现有的认证中间件兼容吗？
> - 数据库迁移有什么风险？
> - 对 API 限流有什么影响？

实现邮件通知系统的第一阶段：
1. 创建 notification_preferences 表的数据库迁移
2. 添加 NotificationPreference 模型
3. 创建 CRUD API 路由

[粘贴 Claude Code 方案的相关部分]

# 继续 Claude Code 会话
claude --continue

> 给我们刚实现的通知偏好 API 写测试。
> 覆盖：CRUD 操作、校验错误、认证要求、
> 数据库约束。

# Claude Code：运行完整测试套件
> 运行测试套件，修复所有失败的用例。

# 然后在 Cursor 中：快速修复剩余问题
# 使用行内编辑模式做精确修改

> 审查这个分支上的所有变更。
> 然后创建一个带有详细描述的 Pull Request。