Claude Code 进阶实战：CLAUDE.md、子代理与规则，把 AI 编程助手调教成团队老兵

---
paths:
  - "src/**/*.ts"
---

# API 开发规则

- 所有 API 端点必须带输入校验
- 报错返回统一格式

---
name: code-reviewer
description: 资深代码审查专家。写/改完代码后主动审查质量、安全与可维护性。适合让 Claude 在写完代码后调用。
tools: Read, Grep, Glob, Bash
model: inherit
---

你是一位资深代码审查员。

审查清单：
- 代码清晰可读、命名良好
- 无重复代码、错误处理完善
- 无硬编码密钥或 API Key
- 有充分的测试覆盖

按优先级输出：关键问题（必须修）/ 警告（应该修）/ 建议（可以考虑）

export ANTHROPIC_API_KEY="你的中转站Key"
export ANTHROPIC_BASE_URL="https://你的中转站地址"   # 以中转站控制台显示为准

#!/usr/bin/env bash
set -u
# ============================================================
#  Claude Code 进阶配置 一键脚本（macOS / Linux / WSL）
#  公开源码，欢迎审查 —— 不放心可先复制给 AI 判断
#  默认配置：云间 API 中转站（https://cloudzone-api.cyou/）
#  生成：CLAUDE.md 模板 + .claude/agents/ 子代理 + Key 配置
# ============================================================

GREEN='\033[0;32m'; YELLOW='\033[1;33m'; RED='\033[0;31m'; CYAN='\033[0;36m'; NC='\033[0m'
info()  { echo -e "${GREEN}[INFO]${NC} $1"; }
warn()  { echo -e "${YELLOW}[WARN]${NC} $1"; }
error() { echo -e "${RED}[ERROR]${NC} $1"; }
step()  { echo -e "${CYAN}[STEP]${NC} $1"; }

CLOUDZONE_URL="https://cloudzone-api.cyou"
CLOUDZONE_API_BASE="https://cloudzone-api.cyou/v1"

detect_network() {
  step "检测网络环境（国内 / 国外）..."
  if curl -fsI --max-time 5 "https://claude.ai" >/dev/null 2>&1; then
    info "可直连 claude.ai，判定为海外网络"
    echo "overseas"
  else
    warn "无法直连 claude.ai，判定为国内网络环境（将自动切换国内镜像）"
    echo "domestic"
  fi
}

check_claude() {
  step "检查 Claude Code..."
  if ! command -v claude >/dev/null 2>&1; then
    warn "未检测到 claude 命令。请先安装 Claude Code（本站《Claude Code 快速上手教程》或官方文档 https://code.claude.com/docs/en/start）后重跑本脚本。"
    return 1
  fi
  info "已安装：$(claude --version 2>&1 | head -1)"
  return 0
}

write_memory_files() {
  step "生成 CLAUDE.md 模板与子代理文件 ..."

  if [ ! -f "CLAUDE.md" ]; then
    cat > CLAUDE.md <<'MDEOF'
# 项目说明（CLAUDE.md）

> 本文件由 CleanResolver 一键脚本生成初稿。Claude Code 每次会话自动加载。
> 建议：补充构建命令、目录约定、代码规范；总行数控制在 200 行以内。

## 构建与测试
- 构建命令：____________（填你的命令，如 npm run build）
- 测试命令：____________

## 项目约定
- ____________

## 不要做
- ____________
MDEOF
    info "已生成 CLAUDE.md 模板（请填入你的项目信息）"
  else
    info "检测到已有 CLAUDE.md，跳过生成"
  fi

  mkdir -p .claude/agents
  if [ ! -f ".claude/agents/code-reviewer.md" ]; then
    cat > .claude/agents/code-reviewer.md <<'MDEOF'
---
name: code-reviewer
description: 资深代码审查专家。写/改完代码后主动审查质量、安全与可维护性。
tools: Read, Grep, Glob, Bash
model: inherit
---

你是一位资深代码审查员。

审查清单：
- 代码清晰可读、命名良好
- 无重复代码、错误处理完善
- 无硬编码密钥或 API Key
- 有充分的测试覆盖

按优先级输出：关键问题（必须修）/ 警告（应该修）/ 建议（可以考虑），并给出具体修改示例。
MDEOF
    info "已生成 .claude/agents/code-reviewer.md"
  fi

  if [ ! -f ".claude/agents/docs-writer.md" ]; then
    cat > .claude/agents/docs-writer.md <<'MDEOF'
---
name: docs-writer
description: 文档编写专家。适合总结代码、生成 README、撰写变更记录。
tools: Read, Grep, Glob, Bash
model: inherit
---

你是一位中文技术文档作者，擅长把复杂实现讲清楚：
- 先列结构再展开，多用步骤和表格
- 代码示例与当前仓库真实代码一致
- 术语首现给出通俗解释
MDEOF
    info "已生成 .claude/agents/docs-writer.md"
  fi
}

configure_api() {
  step "配置 Claude Code 的 API Key..."
  echo ""
  echo "Claude Code 每次对话需要消耗 Claude API 额度。默认推荐云间 API 中转站："
  echo "  · Anthropic 兼容格式，原生支持 Claude Code"
  echo "  · CC MAX（Claude Code 专项套餐）低至官方 0.5 倍"
  echo "  · 香港节点国内直连，无需科学上网"
  echo ""
  echo "是否现在跳转注册并获取 API Key？"
  echo "  Y - 立即跳转至 ${CLOUDZONE_URL}"
  echo "  N - 我已有 Key（官方或第三方），自行输入"
  read -r -p "请选择 [Y/N]: " choice

  local API_KEY=""
  local BASE_URL="$CLOUDZONE_API_BASE"
  if [ "${choice:-N}" = "Y" ] || [ "${choice:-N}" = "y" ]; then
    info "正在打开浏览器..."
    if command -v xdg-open >/dev/null 2>&1; then
      xdg-open "$CLOUDZONE_URL" >/dev/null 2>&1
    elif command -v open >/dev/null 2>&1; then
      open "$CLOUDZONE_URL" >/dev/null 2>&1
    else
      warn "无法自动打开浏览器，请手动访问：$CLOUDZONE_URL"
    fi
    echo "注册后在控制台复制 Key，并确认你的中转站是 Anthropic 兼容格式。"
    read -r -p "粘贴你的 API Key: " API_KEY
    read -r -p "中转地址(直接回车用默认 ${CLOUDZONE_API_BASE}): " input_base
    [ -n "${input_base:-}" ] && BASE_URL="$input_base"
  else
    read -r -s -p "请输入你的 API Key (sk-...): " API_KEY
    echo
    echo "官方 Key 保持默认地址 https://api.anthropic.com；中转站 Key 填其 Anthropic 兼容地址。"
    read -r -p "API 地址(直接回车用默认 https://api.anthropic.com): " input_base
    BASE_URL="${input_base:-https://api.anthropic.com}"
  fi

  if [ -z "${API_KEY:-}" ]; then
    error "未输入 API Key，跳过配置。可稍后手动设置环境变量。"
    return 1
  fi

  local SHELL_RC=""
  case "$SHELL" in
    */zsh)  SHELL_RC="$HOME/.zshrc" ;;
    */bash) SHELL_RC="$HOME/.bashrc" ;;
    *)      SHELL_RC="$HOME/.profile" ;;
  esac

  info "写入环境变量到 $SHELL_RC（仅 ANTHROPIC_API_KEY / ANTHROPIC_BASE_URL，原值备份 .bak）"
  if [ -f "$SHELL_RC" ]; then
    sed -i.bak '/ANTHROPIC_API_KEY/d; /ANTHROPIC_BASE_URL/d' "$SHELL_RC"
  fi
  {
    echo ""
    echo "# Claude Code - 由一键脚本写入"
    echo "export ANTHROPIC_API_KEY=\"$API_KEY\""
    echo "export ANTHROPIC_BASE_URL=\"$BASE_URL\""
  } >> "$SHELL_RC"

  export ANTHROPIC_API_KEY="$API_KEY"
  export ANTHROPIC_BASE_URL="$BASE_URL"

  info "配置完成！"
  echo "  API Key : ${API_KEY:0:10}********"
  echo "  Base URL: $BASE_URL"
  echo ""
  warn "新开终端窗口后永久生效，或立即执行：source $SHELL_RC"
}

main() {
  echo "============================================"
  echo "  Claude Code 进阶配置 一键脚本"
  echo "  适用于 macOS / Linux / WSL"
  echo "  默认接入：云间 API 中转站"
  echo "============================================"
  echo ""

  local NET
  NET=$(detect_network)

  if ! check_claude; then
    warn "脚本跳过安装步骤，仅生成配置模板。"
  fi

  write_memory_files

  configure_api || warn "Key 未配置，可稍后自行 export ANTHROPIC_API_KEY"

  echo ""
  echo "============================================"
  info "全部完成！"
  echo "  1. 打开 claude 会话，输入 /context 确认 Memory files 包含 CLAUDE.md"
  echo "  2. 让 AI 干活前先补全 CLAUDE.md 里的项目信息"
  echo "  3. 说'用 code-reviewer 审查'体验子代理"
  echo "============================================"
}

main "$@"

# ============================================================
#  Claude Code 进阶配置 一键脚本（Windows PowerShell）
#  公开源码，欢迎审查 -- 不放心可先复制给 AI 判断
#  默认配置：云间 API 中转站（https://cloudzone-api.cyou/）
#  生成：CLAUDE.md 模板 + .claude/agents/ 子代理 + Key 配置
# ============================================================
$ErrorActionPreference = "Stop"

function Write-Info  { Write-Host "[INFO] $args" -ForegroundColor Green }
function Write-Warn  { Write-Host "[WARN] $args" -ForegroundColor Yellow }
function Write-Err   { Write-Host "[ERROR] $args" -ForegroundColor Red }
function Write-Step  { Write-Host "[STEP] $args" -ForegroundColor Cyan }

$CLOUDZONE_URL = "https://cloudzone-api.cyou"
$CLOUDZONE_API_BASE = "https://cloudzone-api.cyou/v1"

function Detect-Network {
    Write-Step "检测网络环境（国内 / 国外）..."
    try {
        $null = Invoke-WebRequest -Uri "https://claude.ai" -Method Head -TimeoutSec 5 -UseBasicParsing
        Write-Info "可直连 claude.ai，判定为海外网络"
        return "overseas"
    } catch {
        Write-Warn "无法直连 claude.ai，判定为国内网络环境"
        return "domestic"
    }
}

function Check-Claude {
    Write-Step "检查 Claude Code..."
    if (-not (Get-Command claude -ErrorAction SilentlyContinue)) {
        Write-Warn "未检测到 claude 命令。请先安装 Claude Code（本站《Claude Code 快速上手教程》或官方文档 https://code.claude.com/docs/en/start）后重跑本脚本。"
        return $false
    }
    try { Write-Info "已安装：$(claude --version 2>&1 | Select-Object -First 1)" } catch { }
    return $true
}

function Write-MemoryFiles {
    Write-Step "生成 CLAUDE.md 模板与子代理文件 ..."

    if (-not (Test-Path "CLAUDE.md")) {
        @'
# 项目说明（CLAUDE.md)

> 本文件由 CleanResolver 一键脚本生成初稿。Claude Code 每次会话自动加载。
> 建议：补充构建命令、目录约定、代码规范；总行数控制在 200 行以内。

## 构建与测试
- 构建命令：____________（填你的命令，如 npm run build）
- 测试命令：____________

## 项目约定
- ____________

## 不要做
- ____________
'@ | Set-Content -Path "CLAUDE.md" -Encoding UTF8
        Write-Info "已生成 CLAUDE.md 模板（请填入你的项目信息）"
    } else {
        Write-Info "检测到已有 CLAUDE.md，跳过生成"
    }

    New-Item -ItemType Directory -Force -Path ".claude\agents" | Out-Null
    if (-not (Test-Path ".claude\agents\code-reviewer.md")) {
        @'
---
name: code-reviewer
description: 资深代码审查专家。写/改完代码后主动审查质量、安全与可维护性。
tools: Read, Grep, Glob, Bash
model: inherit
---

你是一位资深代码审查员。

审查清单：
- 代码清晰可读、命名良好
- 无重复代码、错误处理完善
- 无硬编码密钥或 API Key
- 有充分的测试覆盖

按优先级输出：关键问题（必须修）/ 警告（应该修）/ 建议（可以考虑），并给出具体修改示例。
'@ | Set-Content -Path ".claude\agents\code-reviewer.md" -Encoding UTF8
        Write-Info "已生成 .claude/agents/code-reviewer.md"
    }

    if (-not (Test-Path ".claude\agents\docs-writer.md")) {
        @'
---
name: docs-writer
description: 文档编写专家。适合总结代码、生成 README、撰写变更记录。
tools: Read, Grep, Glob, Bash
model: inherit
---

你是一位中文技术文档作者，擅长把复杂实现讲清楚：
- 先列结构再展开，多用步骤和表格
- 代码示例与当前仓库真实代码一致
- 术语首现给出通俗解释
'@ | Set-Content -Path ".claude\agents\docs-writer.md" -Encoding UTF8
        Write-Info "已生成 .claude/agents/docs-writer.md"
    }
}

function Configure-Api {
    Write-Step "配置 Claude Code 的 API Key..."
    Write-Host ""
    Write-Host "Claude Code 每次对话需要消耗 Claude API 额度。默认推荐云间 API 中转站："
    Write-Host "  · Anthropic 兼容格式，原生支持 Claude Code"
    Write-Host "  · CC MAX（Claude Code 专项套餐）低至官方 0.5 倍"
    Write-Host "  · 香港节点国内直连，无需科学上网"
    Write-Host ""
    Write-Host "是否现在跳转注册并获取 API Key？"
    Write-Host "  Y - 立即跳转至 $CLOUDZONE_URL"
    Write-Host "  N - 我已有 Key（官方或第三方），自行输入"
    $choice = Read-Host "请选择 [Y/N]"

    $apiKey = ""
    $baseUrl = $CLOUDZONE_API_BASE
    if ($choice -eq "Y" -or $choice -eq "y") {
        Write-Info "正在打开浏览器..."
        try {
            Start-Process "$CLOUDZONE_URL"
        } catch {
            Write-Warn "无法自动打开浏览器，请手动访问：$CLOUDZONE_URL"
        }
        Write-Host "注册后在控制台复制 Key，并确认你的中转站是 Anthropic 兼容格式。"
    } else {
        $baseUrl = "https://api.anthropic.com"
        Write-Host "官方 Key 保持默认地址 https://api.anthropic.com；中转站 Key 填其 Anthropic 兼容地址。"
    }

    $sec = Read-Host "粘贴你的 API Key（输入时不显示字符）" -AsSecureString
    $bstr = [System.Runtime.InteropServices.Marshal]::SecureStringToBSTR($sec)
    $apiKey = [System.Runtime.InteropServices.Marshal]::PtrToStringAuto($bstr)
    [System.Runtime.InteropServices.Marshal]::ZeroFreeBSTR($bstr)

    if ([string]::IsNullOrWhiteSpace($apiKey)) {
        Write-Err "未输入 API Key，跳过配置。可稍后手动设置环境变量。"
        return $false
    }

    $inputBase = Read-Host "API 地址(直接回车用默认 ${baseUrl})"
    if (-not [string]::IsNullOrWhiteSpace($inputBase)) { $baseUrl = $inputBase }

    # 写入用户级环境变量（永久），并导出到当前会话。原因：Claude Code 从环境变量读取 Key 与端点。
    [Environment]::SetEnvironmentVariable("ANTHROPIC_API_KEY", $apiKey, "User")
    [Environment]::SetEnvironmentVariable("ANTHROPIC_BASE_URL", $baseUrl, "User")
    $env:ANTHROPIC_API_KEY = $apiKey
    $env:ANTHROPIC_BASE_URL = $baseUrl

    Write-Info "配置完成！"
    Write-Host "  API Key : $($apiKey.Substring(0, [Math]::Min(10, $apiKey.Length)))********"
    Write-Host "  Base URL: $baseUrl"
    Write-Host ""
    Write-Warn "新开终端窗口后永久生效（当前会话已立即生效）"
    return $true
}

Write-Host "============================================"
Write-Host "  Claude Code 进阶配置 一键脚本"
Write-Host "  适用于 Windows（PowerShell）"
Write-Host "  默认接入：云间 API 中转站"
Write-Host "============================================"
Write-Host ""

$net = Detect-Network

if (-not (Check-Claude)) {
    Write-Warn "脚本跳过安装步骤，仅生成配置模板。"
}

Write-MemoryFiles

if (-not (Configure-Api)) {
    Write-Warn "Key 未配置，可稍后自行设置 ANTHROPIC_API_KEY"
}

Write-Host ""
Write-Host "============================================"
Write-Info "全部完成！"
Write-Host "  1. 打开 claude 会话，输入 /context 确认 Memory files 包含 CLAUDE.md"
Write-Host "  2. 让 AI 干活前先补全 CLAUDE.md 里的项目信息"
Write-Host "  3. 说'用 code-reviewer 审查'体验子代理"
Write-Host "============================================"