Claude Code目录工程化 | 4SAPI团队模板

开一个项目。
写一个 CLAUDE.md。
让 Claude Code 自己摸索。

Claude Code 能不能干活，不只取决于模型能力，也取决于项目怎么组织它的上下文和权限。

读得懂规则。
改得动代码。
跑得起测试。
守得住边界。
交付得可验收。

Claude Code 会从项目目录和用户级 ~/.claude 中读取 instructions、settings、skills、subagents、memory 等内容。

your-project/
├── CLAUDE.md
├── CLAUDE.local.md              # 个人覆盖，不提交
├── AGENTS.md                    # 可选，给 Codex 等工具复用
├── .claude/
│   ├── settings.json
│   ├── settings.local.json       # 个人覆盖，不提交
│   ├── rules/
│   │   ├── llm-gateway.md
│   │   ├── security.md
│   │   ├── testing.md
│   │   ├── frontend.md
│   │   └── backend-api.md
│   ├── hooks/
│   │   ├── block-secret-reads.sh
│   │   ├── block-dangerous-commands.sh
│   │   └── remind-tests-before-stop.sh
│   ├── commands/
│   │   ├── review-llm-provider.md
│   │   ├── test-4sapi-smoke.md
│   │   └── summarize-ai-cost.md
│   ├── skills/
│   │   ├── 4sapi-provider-migration/
│   │   │   ├── SKILL.md
│   │   │   └── checklist.md
│   │   └── ai-cost-audit/
│   │       ├── SKILL.md
│   │       └── cost-template.md
│   └── agents/
│       ├── security-auditor.md
│       ├── llm-provider-reviewer.md
│       └── docs-writer.md

CLAUDE.md
.claude/settings.json

rules -> hooks -> commands -> skills -> agents

# CLAUDE.md

## Project

这是一个接入 4SAPI 的大模型 API 中转站示例项目，用于统一调用 Claude、GPT、Gemini、GLM 等模型。

## Commands

- Install: `pnpm install`
- Dev: `pnpm dev`
- Lint: `pnpm lint`
- Test: `pnpm test`
- Build: `pnpm build`

## Architecture

- `packages/llm/`：LLM provider、模型路由、错误处理
- `apps/web/`：前端页面
- `apps/api/`：后端 API
- `docs/`：接入说明和运维文档

## LLM Rules

- 不要把 4SAPI Key 写进代码
- 不要在前端暴露任何模型 Key
- 所有模型调用必须经过后端 provider 层
- 新增模型时同步更新 `.env.example`
- 修改 LLM provider 后必须运行相关测试
- 日志不能记录完整用户隐私、API Key、完整 prompt

## Before Editing

- 先找相关文件
- 先给最小改动计划
- 不要重构无关模块
- 涉及 3 个以上文件时先列清单

回答我时用更口语的语气。
我喜欢先看表格。
我的本地端口是 5174。
我常用 Windows PowerShell。

# CLAUDE.local.md

## Personal Preferences

- 默认用中文回复我
- 我本地使用 Windows PowerShell
- 本机开发端口优先使用 5174
- 解释方案时先给结论，再给命令

CLAUDE.local.md
.claude/settings.local.json

帮助整个团队保持一致 -> 提交到仓库
只反映你个人习惯 -> 放 local

{
  "$schema": "https://json.schemastore.org/claude-code-settings.json",
  "permissions": {
    "allow": [
      "Bash(pnpm lint)",
      "Bash(pnpm test *)",
      "Bash(pnpm build)",
      "Bash(rg *)",
      "Bash(git status)",
      "Bash(git diff *)"
    ],
    "deny": [
      "Read(./.env)",
      "Read(./.env.*)",
      "Read(./secrets/**)",
      "Read(./config/production.json)",
      "Bash(rm -rf *)",
      "Bash(curl *|sh)",
      "Bash(wget *|sh)"
    ]
  }
}

.claude/rules/
  llm-gateway.md
  security.md
  testing.md
  frontend.md
  backend-api.md

# LLM Gateway Rules

适用于所有模型调用相关代码。

## 必须遵守

- 所有模型调用必须经过 `packages/llm/`
- 使用环境变量读取 `LLM_BASE_URL`、`LLM_API_KEY`、`LLM_MODEL`
- 兼容 OpenAI-style `/chat/completions`
- 支持 4SAPI 作为默认中转入口
- provider 需要返回统一错误类型

## 禁止

- 不要在前端直接请求 4SAPI
- 不要把 API Key 写入测试快照
- 不要把完整 prompt 写入日志

# Security Rules

- 不读取 `.env`、`secrets/`、生产配置
- 不输出 API Key、token、cookie
- 日志必须脱敏
- 涉及支付、权限、生产数据时先停下来说明风险
- 删除、移动、重命名文件前必须列清单

# Testing Rules

修改 LLM provider 后至少运行：

```bash
pnpm test packages/llm

pnpm test apps/web
pnpm build

`rules/` 的价值是：

```text
让项目规则能持续维护，而不是塞爆 CLAUDE.md。

hooks 是自动触发。
commands 是你主动调用。

#!/usr/bin/env bash

input="$(cat)"

if echo "$input" | grep -E '\\.env|secrets|production\\.json|api_key|token' >/dev/null; then
  echo "Blocked: this operation may access secrets or production config."
  exit 2
fi

exit 0

#!/usr/bin/env bash

echo "Reminder: if LLM provider files changed, run pnpm test packages/llm and update status."
exit 0

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Read|Bash",
        "hooks": [
          {
            "type": "command",
            "command": ".claude/hooks/block-secret-reads.sh"
          }
        ]
      }
    ],
    "Stop": [
      {
        "matcher": "*",
        "hooks": [
          {
            "type": "command",
            "command": ".claude/hooks/remind-tests-before-stop.sh"
          }
        ]
      }
    ]
  }
}

# Review LLM Provider

请审查当前 diff 中和 LLM provider 相关的改动。

重点检查：

1. 是否仍然通过 4SAPI / OpenAI-compatible base_url 调用
2. 是否泄露 API Key
3. 是否记录完整 prompt
4. 是否破坏旧模型 fallback
5. 是否更新 `.env.example`
6. 是否补充测试
7. 是否有可读错误提示

先列问题，不要直接修改。

# Test 4SAPI Smoke

请执行一次最小 smoke test。

要求：

1. 不读取真实 `.env`
2. 使用测试环境变量或 mock
3. 验证 base_url、model、timeout、错误处理
4. 输出测试命令和结果
5. 不把 Key 打印到终端

把常用 prompt 变成团队统一入口。

---
name: 4sapi-provider-migration
description: "把现有 OpenAI/Claude/Gemini 调用迁移到 4SAPI 大模型 API 中转站，并保持测试、文档和回滚路径完整。"
---

# 4SAPI Provider Migration

## When To Use

当用户要把现有模型调用统一迁移到 4SAPI 或 OpenAI-compatible gateway 时使用。

## Workflow

1. 先定位所有模型调用位置
2. 判断 SDK 是否支持自定义 base_url
3. 设计最小改动方案
4. 新增或复用 provider 层
5. 更新 `.env.example`
6. 添加成功、401、429、5xx、timeout 测试
7. 更新 README
8. 输出回滚方案

## Safety

- 不读取真实 `.env`
- 不打印 API Key
- 不改生产配置
- 不重构无关模块

## Output

- 修改文件清单
- 验证命令
- 风险点
- 回滚方式

---
name: ai-cost-audit
description: "审计项目中的大模型调用成本，找出高 token、重复重试、模型路由不合理和日志缺口。"
---

# AI Cost Audit

## Workflow

1. 查找所有 LLM 调用
2. 统计是否记录 token
3. 检查是否设置 max_tokens
4. 检查重试上限
5. 检查是否所有任务都使用最贵模型
6. 给出 4SAPI 路由优化建议

## Output

用表格输出：

- 文件
- 风险
- 成本影响
- 建议
- 是否阻塞上线

---
name: security-auditor
description: "审计代码中的 API Key、日志隐私、权限边界和生产配置风险。"
tools:
  - Read
  - Grep
  - Glob
---

# Security Auditor

你是安全审计子代理。

只做审计，不直接修改代码。

重点检查：

- API Key 是否可能泄露
- `.env` 是否被读取或提交
- 日志是否记录完整 prompt
- 前端是否暴露模型 Key
- 生产配置是否被改动
- 4SAPI Key 是否只在后端使用

输出：

- 阻塞问题
- 非阻塞建议
- 需要人工确认的问题

---
name: llm-provider-reviewer
description: "审查 LLM provider、模型路由、fallback、4SAPI 接入和错误处理。"
tools:
  - Read
  - Grep
  - Glob
---

# LLM Provider Reviewer

请检查模型调用链路是否清晰：

前端 -> 后端 -> provider -> 4SAPI -> 上游模型

重点看：

- 是否支持自定义 base_url
- 是否有模型 fallback
- 是否有 401/429/5xx/timeout 错误处理
- 是否更新文档和环境变量示例
- 是否有测试覆盖

项目文件可以提交到 Git 给团队共享。
~/.claude 是个人配置，跨项目生效。

帮助团队一致交付 -> 项目级
只帮助个人习惯更舒服 -> 用户级

CLAUDE.md
.claude/settings.json

.claude/rules/

.claude/hooks/

.claude/commands/
.claude/skills/

.claude/agents/

先让 Claude Code 稳定，再让它强大。

全局内容留在 CLAUDE.md。
专项内容拆到 rules。
流程内容做成 commands 或 skills。

1. 根目录是否有简洁 CLAUDE.md
2. 是否把个人偏好放进 CLAUDE.local.md
3. .gitignore 是否包含 CLAUDE.local.md 和 settings.local.json
4. settings.json 是否禁止读取 .env 和 secrets
5. 4SAPI provider 规则是否写入 rules/llm-gateway.md
6. 测试命令是否写清楚
7. 是否有 provider review command
8. 是否有成本审计 skill
9. 是否有 security-auditor agent
10. hooks 是否只做确定性安全护栏
11. 是否定期清理无用 commands/skills/agents
12. 是否所有模型调用都经过后端 provider 层

最高效的 .claude/ 目录，不是功能最多，而是每一层都有清晰职责。

CLAUDE.md
.claude/settings.json

rules -> hooks -> commands -> skills -> agents