让 Claude Code 在百万行代码仓库里真正好用：实战经验与配置指南

# 项目概览

这是一个 Python + TypeScript 单体仓库，包含 3 个主要服务：
- `services/api/` — FastAPI 后端，Python 3.11
- `services/web/` — Next.js 前端，Node 20
- `services/auth/` — 认证服务，Go 1.22

## 构建与测试

每个服务有独立的构建命令，不要跨服务混用：

```bash
# API 服务
cd services/api && make test          # 运行测试
cd services/api && make lint          # Ruff lint
cd services/api && make migrate       # 数据库迁移

# 前端服务
cd services/web && npm run test       # Jest 测试
cd services/web && npm run build      # 生产构建

# 认证服务
cd services/auth && go test ./...     # Go 测试
cd services/auth && go build -o bin/auth  # 编译

子目录级别的 CLAUDE.md 可以更具体。比如 `services/auth/CLAUDE.md`：

```markdown
# 认证服务

## 关键文件
- `cmd/server/main.go` — 入口
- `internal/token/jwt.go` — JWT 生成与验证核心逻辑
- `internal/store/postgres.go` — 用户存储

## 本地开发
```bash
go run cmd/server/main.go --config local.yaml

## 遗留代码的探索策略：帮 Claude Code 找到入口

几十年的遗留系统通常没有清晰的目录结构，构建脚本可能散落在各处。Anthropic 的经验是：**在 CLAUDE.md 中明确标注"入口文件"和"关键配置"的位置**，比试图描述整个架构更有效。

一个针对遗留 C 项目的 CLAUDE.md 片段：

```markdown
## 遗留代码导航

这个项目没有标准目录结构，以下是关键入口：

- 主程序入口：`src/main/main.c`（注意：不是 `main.c`，有子目录）
- 构建系统：根目录 `Makefile`，但子模块各有自己的 `makefile`（小写）
- 配置加载：`src/config/parser.c` — 所有运行时配置从这里读取
- 数据库交互：`src/db/` 目录，用的是嵌入式 SQLite，不是外部服务

## 构建警告

- `make all` 在根目录运行，但会跳过 `src/experimental/`（那是未完成模块）
- 如果遇到 "undefined reference to `legacy_connect`"，检查 `src/compat/` 是否被编译

#!/bin/bash
# gather-context.sh — 为 Claude Code 跨仓库工作准备上下文
# 用法：在任意仓库目录运行，生成 CONTEXT.md 供 Claude Code 参考

REPOS=(
  "/path/to/org/api-core"
  "/path/to/org/api-gateway"
  "/path/to/org/shared-libs"
  "/path/to/org/auth-service"
)

OUTPUT="CONTEXT.md"

echo "# 跨仓库上下文摘要" > "$OUTPUT"
echo "" >> "$OUTPUT"
echo "生成时间: $(date)" >> "$OUTPUT"
echo "" >> "$OUTPUT"

for repo in "${REPOS[@]}"; do
  if [ -d "$repo" ]; then
    echo "## 仓库: $(basename "$repo")" >> "$OUTPUT"
    echo "" >> "$OUTPUT"

    # 提取该仓库的 CLAUDE.md（如果存在）
    if [ -f "$repo/CLAUDE.md" ]; then
      echo "### 该仓库的 CLAUDE.md 内容" >> "$OUTPUT"
      cat "$repo/CLAUDE.md" >> "$OUTPUT"
      echo "" >> "$OUTPUT"
    fi

    # 提取关键配置文件摘要
    for config in "package.json" "pyproject.toml" "go.mod" "Makefile" "docker-compose.yml"; do
      if [ -f "$repo/$config" ]; then
        echo "### $config 关键信息" >> "$OUTPUT"
        head -30 "$repo/$config" >> "$OUTPUT"
        echo "" >> "$OUTPUT"
      fi
    done

    # 提取最近 git log（了解近期变更方向）
    echo "### 最近 5 次提交" >> "$OUTPUT"
    cd "$repo" && git log --oneline -5 >> "$OUTPUT"
    cd - > /dev/null
    echo "" >> "$OUTPUT"
  else
    echo "## 仓库: $(basename "$repo") — 目录不存在，跳过" >> "$OUTPUT"
    echo "" >> "$OUTPUT"
  fi
done

echo "上下文已写入 $OUTPUT"
echo "在 Claude Code 中可以要求它参考此文件进行跨仓库分析"

chmod +x gather-context.sh
./gather-context.sh
# 然后在 Claude Code 对话中提及 CONTEXT.md

# GitHub Actions 片段：检查 CLAUDE.md 是否过时
name: Check CLAUDE.md freshness
on:
  schedule:
    - cron: '0 9 * * 1'  # 每周一上午 9 点
jobs:
  check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Check CLAUDE.md last modified
        run: |
          DAYS=$(( ( $(date +%s) - $(git log -1 --format="%ct" CLAUDE.md) ) / 86400 ))
          if [ "$DAYS" -gt 90 ]; then
            echo "::warning::CLAUDE.md 已 $DAYS 天未更新，请检查是否反映当前项目状态"
          fi