Claude Code .claude 目录完整指南：每个文件和目录的作用与最佳实践

// .claude/settings.json（提交到 Git，团队共享）
{
  "permissions": {
    "allow": [
      "Bash(npm test)",
      "Bash(npm run lint)",
      "Bash(npm run build)",
      "Bash(git log *)",
      "Bash(git diff *)",
      "Bash(git status)",
      "Bash(gh pr view *)",
      "Bash(gh issue view *)"
    ],
    "deny": [
      "Bash(git push --force)",
      "Bash(rm -rf *)",
      "Bash(DROP TABLE *)"
    ]
  },
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "npm run lint --fix 2>/dev/null; echo 'lint done'"
          }
        ]
      }
    ]
  }
}

// .claude/settings.local.json（不提交，个人使用）
{
  "permissions": {
    "allow": [
      "Bash(npm run dev)",
      "Bash(ngrok *)"
    ]
  },
  "env": {
    "DATABASE_URL": "postgresql://localhost:5432/myapp_dev"
  }
}

---
name: deploy-staging
description: 部署到 staging 环境
disable-model-invocation: true    # 只允许用户手动触发
allowed-tools: Bash(npm *) Bash(git *) Bash(gh *)
---

## 部署步骤

1. 运行测试：`npm test`（失败则停止）
2. 构建：`npm run build`
3. 推送到 staging 分支：`git push origin HEAD:staging`
4. 等待 CI 完成（查看：`gh run watch`）
5. 验证健康检查：`curl https://staging.myapp.com/health`

---
# .claude/agents/security-reviewer.md
name: security-reviewer
description: 专注安全漏洞的代码审查专家。在处理 src/api/ 或涉及用户数据时自动委托
tools:
  - Read
  - Glob
  - Grep
  - Bash(git diff *)
model: claude-opus-4-5
effort: high
---

你是一个专注于安全漏洞检测的代码审查专家。

对于每段代码，你需要检查：
1. SQL 注入（特别是字符串拼接的查询）
2. XSS（用户输入输出到 HTML）
3. CSRF（缺失的 CSRF 保护）
4. 认证/授权问题（缺失检查、越权访问）
5. 敏感数据暴露（日志/响应里的密码、密钥）

输出格式：
- 🔴 Critical（必须修复）
- 🟡 Warning（建议修复）
- 🔵 Info（参考）

每个发现包含：位置（文件:行号）、问题描述、修复建议。

---
# .claude/agents/test-writer.md
name: test-writer
description: 专门编写高质量测试代码的 Agent
tools:
  - Read
  - Write
  - Edit
  - Glob
  - Grep
  - Bash(npm test *)
---

你是一个专注于编写高覆盖率、高质量测试代码的专家。

测试原则：
- 每个测试只验证一个行为
- 测试名描述"应该…"（Given/When/Then）
- 优先集成测试，单元测试覆盖复杂逻辑
- Mock 只用于外部依赖（网络、数据库），不 mock 内部模块
- 边界情况比 Happy Path 更重要

为每个函数生成：
1. 正常路径测试（2-3 个）
2. 边界情况（empty/null/极值）
3. 错误路径（异常、无效输入）

# 使用 /init 生成基础 CLAUDE.md（会分析代码库）
claude
> /init

# 创建目录结构
mkdir -p .claude/{rules,skills,agents}

# 查看 .claude 目录里有什么
ls -la .claude/