AI 代理配置策略 (配置与安全)

何时使用此技能

• 为新项目搭建 AI 代理环境
• 编写和优化项目描述文件
• 配置钩子/技能/插件
• 建立安全策略
• 在团队内共享配置

1. 项目描述文件编写策略

概述

项目描述文件（如 CLAUDE.md、README 等）是面向 AI 的项目手册。AI 代理会以最高优先级参考这些文件。

自动生成 (Claude Code)

/init  # Claude 分析代码库并生成项目描述草稿

必需的结构章节

# 项目：[项目名称]

## 技术栈
- **前端**：React + TypeScript
- **后端**：Node.js + Express
- **数据库**：PostgreSQL
- **ORM**：Drizzle

## 编码规范
- 使用 TypeScript 严格模式
- 优先使用服务端组件而非客户端组件
- 使用 `async/await` 替代 `.then()`
- 始终使用 Zod 验证用户输入

## 禁止事项
- 绝不能提交 `.env` 文件
- 绝不能使用 `any` 类型
- 绝不能绕过身份验证检查
- 绝不能在前端代码中暴露 API 密钥

## 常用命令
- `npm run dev`：启动开发服务器
- `npm run build`：构建生产版本
- `npm run test`：运行测试

编写原则：简洁的艺术

糟糕的示例（冗长）：

我们的认证系统基于 NextAuth.js 构建，它是一个为 Next.js
应用提供的完整认证解决方案...（5行以上的解释）

优秀的示例（简洁）：

## 认证
- NextAuth.js 配合 Credentials 提供者
- JWT 会话策略
- **禁止**：绕过认证检查、暴露会话密钥

渐进式添加原则

“从没有项目描述文件开始。当你发现自己反复说明同样的事情时，再添加内容。”
—— 这个原则能有效保持项目文件的简洁和高效。

2. 钩子配置策略 (Claude Code)

概述

钩子是在特定事件发生时自动执行的 Shell 命令。它们是 AI 行为的护栏。

钩子事件类型

安全钩子配置示例

// ~/.claude/settings.json
{
  "hooks": {
    "PreToolUse": [
      {
        "pattern": "rm -rf /",
        "action": "block",
        "message": "已阻止删除根目录的操作"
      },
      {
        "pattern": "rm -rf /*",
        "action": "block",
        "message": "已阻止危险的删除命令"
      },
      {
        "pattern": "sudo rm",
        "action": "warn",
        "message": "警告：正在执行带 sudo 的删除命令"
      },
      {
        "pattern": "curl * | sh",
        "action": "block",
        "message": "已阻止通过管道执行脚本"
      },
      {
        "pattern": "chmod 777",
        "action": "warn",
        "message": "警告：正在设置过高的权限"
      }
    ]
  }
}

3. 技能配置策略

技能与其他配置的对比

选型指南

始终适用的通用规则 → 放入项目描述文件
仅在特定任务需要的知识 → 制作成技能 (更节省令牌)
频繁使用的快捷命令 → 设置成斜杠命令
需要与外部服务集成 → 使用插件 / MCP

创建自定义技能

# 创建技能目录
mkdir -p ~/.claude/skills/my-skill

# 编写 SKILL.md 文件
cat > ~/.claude/skills/my-skill/SKILL.md << 'EOF'
---
name: my-skill
description: 我的自定义技能
platforms: [Claude, Gemini, ChatGPT]
---

# 我的技能

## 何时使用
- 当需要处理特定任务时

## 操作步骤
1. 第一步
2. 第二步
EOF

4. 安全策略

禁止操作

绝对禁止

• 在主机系统上使用无限制的权限模式
• 自动批准删除根目录的命令
• 提交 .env、credentials.json 等密钥文件
• 在代码中硬编码 API 密钥

需要谨慎操作

• 不加区分地批准 sudo 命令
• 运行 curl | sh 格式的脚本
• 使用 chmod 777 设置过高权限
• 连接到未知的 MCP 服务器

批准命令审计

# 使用 cc-safe 工具检查危险命令
npx cc-safe .
npx cc-safe ~/projects

# 检测目标：
# - sudo, rm -rf, chmod 777
# - curl | sh, wget | bash
# - git reset --hard, git push --force
# - npm publish, docker run --privileged

安全自动批准 (Claude Code)

# 仅自动批准安全的命令
/sandbox "npm test"
/sandbox "npm run lint"
/sandbox "git status"
/sandbox "git diff"

# 模式匹配批准
/sandbox "git *"       # 所有 git 命令
/sandbox "npm test *"  # 所有与 npm test 相关的命令

# MCP 工具模式
/sandbox "mcp__server__*"

5. 团队配置共享

项目配置结构

project/
├── .claude/                    # Claude Code 设置
│   ├── team-settings.json
│   ├── hooks/
│   └── skills/
├── .agent-skills/              # 通用技能库
│   ├── backend/
│   ├── frontend/
│   └── ...
├── CLAUDE.md                   # 针对 Claude 的项目描述
├── .cursorrules               # Cursor 编辑器设置
└── ...

team-settings.json 示例

{
  "permissions": {
    "allow": [
      "Read(src/)",
      "Write(src/)",
      "Bash(npm test)",
      "Bash(npm run lint)"
    ],
    "deny": [
      "Bash(rm -rf /)",
      "Bash(sudo *)"
    ]
  },
  "hooks": {
    "PreToolUse": {
      "command": "bash",
      "args": ["-c", "echo '团队钩子：正在验证...'"]
    }
  },
  "mcpServers": {
    "company-db": {
      "command": "npx",
      "args": ["@company/db-mcp"]
    }
  }
}

团队共享工作流

将 .claude/ 文件夹提交到 Git → 团队成员克隆项目 → 相同的设置自动生效 → 团队标准得以保持

6. 多代理配置

各代理的配置文件

共享技能目录结构

.agent-skills/
├── backend/          # 后端相关技能
├── frontend/         # 前端相关技能
├── code-quality/     # 代码质量相关技能
├── infrastructure/   # 基础设施相关技能
├── documentation/    # 文档编写相关技能
├── project-management/ # 项目管理相关技能
├── search-analysis/  # 搜索与分析相关技能
└── utilities/        # 通用工具技能

7. 环境配置检查清单

初始设置

• 创建项目描述文件（可使用 /init 命令或手动编写）
• 设置终端别名（如 c, cc, g, cx）
• 配置外部编辑器（export EDITOR=vim）
• 根据需要连接 MCP 服务器

安全设置

• 为危险命令配置钩子进行拦截
• 审查已批准的命令列表（使用 cc-safe）
• 确保 .env 文件已被添加到 .gitignore
• 准备容器环境（用于进行实验性操作）

团队设置

• 将 .claude/ 文件夹提交到 Git 仓库
• 编写 team-settings.json 文件
• 创建团队标准的项目描述文件模板

快速参考

配置文件位置汇总

~/.claude/settings.json     # 用户级全局设置
~/.claude/skills/           # 用户级全局技能
.claude/settings.json       # 项目级设置
.claude/skills/             # 项目级技能
.agent-skills/              # 通用技能库（可跨项目）
CLAUDE.md                   # 项目的 AI 使用手册

安全优先级

1. 使用钩子（Hooks）拦截危险命令
2. 使用 /sandbox 仅自动批准安全的命令
3. 使用 cc-safe 定期进行安全审计
4. 仅在容器环境中进行实验性操作

令牌效率指南

项目描述文件：始终加载（务必保持简洁）
技能：按需加载（更节省令牌）
.toon 模式：可节省高达 95% 的令牌消耗