agent-configuration

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

AI Agent Configuration Policy (Configuration & Security)

AI Agent 配置策略（配置与安全）

When to use this skill

何时使用本技能

Build AI agent environment for new projects
Write and optimize project description files
Configure Hooks/Skills/Plugins
Establish security policies
Share team configurations

为新项目搭建AI Agent环境
编写与优化项目描述文件
配置Hooks/Skills/Plugins
建立安全策略
共享团队配置

1. Project Description File Writing Policy

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

Overview

概述

Project description files (CLAUDE.md, README, etc.) are project manuals for AI. AI agents reference these files with top priority.

项目描述文件（CLAUDE.md、README等）是面向AI的项目手册，AI Agent会优先参考这些文件。

Auto-generate (Claude Code)

自动生成（Claude Code）

bash

/init  # Claude analyzes the codebase and generates a draft

bash

/init  # Claude分析代码库并生成草稿

Required Section Structure

必填章节结构

markdown

undefined

markdown

undefined

Project: [Project Name]

Project: [项目名称]

Tech Stack

Frontend: React + TypeScript
Backend: Node.js + Express
Database: PostgreSQL
ORM: Drizzle

Frontend: React + TypeScript
Backend: Node.js + Express
Database: PostgreSQL
ORM: Drizzle

Coding Standards

Use TypeScript strict mode
Prefer server components over client components
Use
```
async/await
```
instead of
```
.then()
```
Always validate user input with Zod

Use TypeScript strict mode
Prefer server components over client components
Use
```
async/await
```
instead of
```
.then()
```
Always validate user input with Zod

DO NOT

Never commit
```
.env
```
files
Never use
```
any
```
type in TypeScript
Never bypass authentication checks
Never expose API keys in client code

Never commit
```
.env
```
files
Never use
```
any
```
type in TypeScript
Never bypass authentication checks
Never expose API keys in client code

Common Commands

```
npm run dev
```
: Start development server
```
npm run build
```
: Build for production
```
npm run test
```
: Run tests

undefined

```
npm run dev
```
: Start development server
```
npm run build
```
: Build for production
```
npm run test
```
: Run tests

undefined

Writing Principles: The Art of Conciseness

编写原则：简洁的艺术

Bad (verbose):

markdown

Our authentication system is built using NextAuth.js, which is a
complete authentication solution for Next.js applications...
(5+ lines of explanation)

Good (concise):

markdown

undefined

反面示例（冗长）：

markdown

Our authentication system is built using NextAuth.js, which is a
complete authentication solution for Next.js applications...
(5+ lines of explanation)

正面示例（简洁）：

markdown

undefined

Authentication

NextAuth.js with Credentials provider
JWT session strategy
DO NOT: Bypass auth checks, expose session secrets

undefined

NextAuth.js with Credentials provider
JWT session strategy
DO NOT: Bypass auth checks, expose session secrets

undefined

Incremental Addition Principle

增量添加原则

"Start without a project description file. Add content when you find yourself repeating the same things."

"无需一开始就编写完整的项目描述文件，当你发现自己在重复说明相同内容时，再补充到文件中即可。"

2. Hooks Configuration Policy (Claude Code)

2. Hooks 配置策略（Claude Code）

Overview

概述

Hooks are shell commands that run automatically on specific events. They act as guardrails for AI.

Hooks是在特定事件触发时自动运行的shell命令，是AI的防护栏。

Hook Event Types

Hook 事件类型

Hook	Trigger	Use Case
`PreToolUse`	Before tool execution	Block dangerous commands
`PostToolUse`	After tool execution	Log recording, send notifications
`PermissionRequest`	On permission request	Auto approve/deny
`Notification`	On notification	External system integration
`SubagentStart`	Subagent start	Monitoring
`SubagentStop`	Subagent stop	Result collection

Hook	触发时机	使用场景
`PreToolUse`	工具执行前	拦截危险命令
`PostToolUse`	工具执行后	日志记录、发送通知
`PermissionRequest`	权限申请时	自动批准/拒绝
`Notification`	收到通知时	外部系统集成
`SubagentStart`	子Agent启动时	监控
`SubagentStop`	子Agent停止时	结果收集

Security Hooks Configuration

安全 Hooks 配置

json

// ~/.claude/settings.json
{
  "hooks": {
    "PreToolUse": [
      {
        "pattern": "rm -rf /",
        "action": "block",
        "message": "Block root directory deletion"
      },
      {
        "pattern": "rm -rf /*",
        "action": "block",
        "message": "Block dangerous deletion command"
      },
      {
        "pattern": "sudo rm",
        "action": "warn",
        "message": "Caution: sudo delete command"
      },
      {
        "pattern": "curl * | sh",
        "action": "block",
        "message": "Block piped script execution"
      },
      {
        "pattern": "chmod 777",
        "action": "warn",
        "message": "Caution: excessive permission setting"
      }
    ]
  }
}

json

// ~/.claude/settings.json
{
  "hooks": {
    "PreToolUse": [
      {
        "pattern": "rm -rf /",
        "action": "block",
        "message": "Block root directory deletion"
      },
      {
        "pattern": "rm -rf /*",
        "action": "block",
        "message": "Block dangerous deletion command"
      },
      {
        "pattern": "sudo rm",
        "action": "warn",
        "message": "Caution: sudo delete command"
      },
      {
        "pattern": "curl * | sh",
        "action": "block",
        "message": "Block piped script execution"
      },
      {
        "pattern": "chmod 777",
        "action": "warn",
        "message": "Caution: excessive permission setting"
      }
    ]
  }
}

3. Skills Configuration Policy

3. Skills 配置策略

Skills vs Other Settings Comparison

Skills 与其他设置的对比

Feature	Load Timing	Primary Users	Token Efficiency
Project Description File	Always loaded	Project team	Low (always loaded)
Skills	Load on demand	AI auto	High (on-demand)
Slash Commands	On user call	Developers	Medium
Plugins/MCP	On install	Team/Community	Varies

功能	加载时机	主要使用者	Token 效率
项目描述文件	始终加载	项目团队	低（持续占用）
Skills	按需加载	AI自动调用	高（仅使用时加载）
斜杠命令	用户调用时	开发者	中等
Plugins/MCP	安装后可用	团队/社区	不固定

Selection Guide

选型指南

Rules that always apply → Project Description File
Knowledge needed only for specific tasks → Skills (token efficient)
Frequently used commands → Slash Commands
External service integration → Plugins / MCP

始终生效的规则 → 项目描述文件
仅特定任务需要的知识 → Skills（Token效率更高）
高频使用的命令 → 斜杠命令
外部服务集成 → Plugins / MCP

Custom Skill Creation

自定义 Skill 创建

bash

undefined

bash

undefined

Create skill directory

mkdir -p ~/.claude/skills/my-skill

Write SKILL.md

cat > ~/.claude/skills/my-skill/SKILL.md << 'EOF'

name: my-skill description: My custom skill platforms: [Claude, Gemini, ChatGPT]

cat > ~/.claude/skills/my-skill/SKILL.md << 'EOF'

name: my-skill description: My custom skill platforms: [Claude, Gemini, ChatGPT]

My Skill

When to use

When needed for specific tasks

When needed for specific tasks

Instructions

First step
Second step EOF

---

First step
Second step EOF

---

4. Security Policy

4. 安全策略

Prohibited Actions (DO NOT)

禁止操作（DO NOT）

Absolutely Forbidden

绝对禁止

Using unrestricted permission mode on host systems
Auto-approving root directory deletion commands
Committing secret files like
```
.env
```
,
```
credentials.json
```
Hardcoding API keys

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

Requires Caution

需要谨慎操作

Indiscriminate approval of
```
sudo
```
commands
Running scripts in
```
curl | sh
```
format
Setting excessive permissions with
```
chmod 777
```
Connecting to unknown MCP servers

随意批准
```
sudo
```
命令
运行
```
curl | sh
```
格式的脚本
使用
```
chmod 777
```
设置过高权限
连接未知MCP服务器

Approved Command Audit

已批准命令审计

bash

undefined

bash

undefined

Check for dangerous commands with cc-safe tool

npx cc-safe . npx cc-safe ~/projects

Detection targets:

- sudo, rm -rf, chmod 777

- curl | sh, wget | bash

- git reset --hard, git push --force

- npm publish, docker run --privileged

undefined

undefined

Safe Auto-approval (Claude Code)

安全自动批准（Claude Code）

bash

undefined

bash

undefined

Auto-approve only safe commands

/sandbox "npm test" /sandbox "npm run lint" /sandbox "git status" /sandbox "git diff"

Pattern approval

/sandbox "git *" # All git commands /sandbox "npm test *" # npm test related

MCP tool patterns

/sandbox "mcp__server__*"

---

/sandbox "mcp__server__*"

---

5. Team Configuration Sharing

5. 团队配置共享

Project Configuration Structure

项目配置结构

project/
├── .claude/                    # Claude Code settings
│   ├── team-settings.json
│   ├── hooks/
│   └── skills/
├── .agent-skills/              # Universal skills
│   ├── backend/
│   ├── frontend/
│   └── ...
├── CLAUDE.md                   # Project description for Claude
├── .cursorrules               # Cursor settings
└── ...

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

team-settings.json Example

team-settings.json 示例

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 'Team hook: validating...'"]
    }
  },
  "mcpServers": {
    "company-db": {
      "command": "npx",
      "args": ["@company/db-mcp"]
    }
  }
}

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 'Team hook: validating...'"]
    }
  },
  "mcpServers": {
    "company-db": {
      "command": "npx",
      "args": ["@company/db-mcp"]
    }
  }
}

Team Sharing Workflow

团队共享工作流

Commit .claude/ folder → Team members Clone → Same settings automatically applied → Team standards maintained

提交.claude/文件夹到Git → 团队成员克隆项目 → 自动应用相同配置 → 维持团队标准统一

6. Multi-Agent Configuration

6. 多Agent配置

Per-Agent Configuration Files

各Agent对应配置文件

Agent	Config File	Location
Claude Code	CLAUDE.md, settings.json	Project root, ~/.claude/
Gemini CLI	.geminirc	Project root, ~/
Cursor	.cursorrules	Project root
ChatGPT	Custom Instructions	UI settings

Agent	配置文件	存放位置
Claude Code	CLAUDE.md, settings.json	项目根目录, ~/.claude/
Gemini CLI	.geminirc	项目根目录, ~/
Cursor	.cursorrules	项目根目录
ChatGPT	自定义指令	UI设置中

Shared Skills Directory

共享技能目录

.agent-skills/
├── backend/
├── frontend/
├── code-quality/
├── infrastructure/
├── documentation/
├── project-management/
├── search-analysis/
└── utilities/

.agent-skills/
├── backend/
├── frontend/
├── code-quality/
├── infrastructure/
├── documentation/
├── project-management/
├── search-analysis/
└── utilities/

7. Environment Configuration Checklist

7. 环境配置检查清单

Initial Setup

初始设置

Create project description file (
```
/init
```
or manual)
Set up terminal aliases (
```
c
```
,
```
cc
```
,
```
g
```
,
```
cx
```
)
Configure external editor (
```
export EDITOR=vim
```
)
Connect MCP servers (if needed)

创建项目描述文件（使用
```
/init
```
生成或手动编写）
设置终端别名（
```
c
```
、
```
cc
```
、
```
g
```
、
```
cx
```
）
配置外部编辑器（
```
export EDITOR=vim
```
）
连接MCP服务器（如需）

Security Setup

安全设置

Configure Hooks for dangerous commands
Review approved command list (
```
cc-safe
```
)
Verify .env file in .gitignore
Prepare container environment (for experimentation)

配置Hooks拦截危险命令
用
```
cc-safe
```
检查已批准命令列表
确认.env文件已加入.gitignore
准备容器环境（用于实验操作）

Team Setup

团队设置

Commit .claude/ folder to Git
Write team-settings.json
Team standard project description file template

将.claude/文件夹提交到Git
编写team-settings.json
准备团队标准项目描述文件模板

Quick Reference

快速参考

Configuration File Locations

配置文件位置

~/.claude/settings.json     # Global settings
~/.claude/skills/           # Global skills
.claude/settings.json       # Project settings
.claude/skills/             # Project skills
.agent-skills/              # Universal skills
CLAUDE.md                   # Project AI manual

~/.claude/settings.json     # 全局设置
~/.claude/skills/           # 全局技能
.claude/settings.json       # 项目级设置
.claude/skills/             # 项目级技能
.agent-skills/              # 通用技能
CLAUDE.md                   # 项目AI手册

Security Priority

安全优先级

1. Block dangerous commands with Hooks
2. Auto-approve only safe commands with /sandbox
3. Regular audit with cc-safe
4. Experiment mode in containers only

1. 用Hooks拦截危险命令
2. 仅用/sandbox自动批准安全命令
3. 定期用cc-safe审计
4. 仅在容器中使用实验模式

Token Efficiency

Token效率说明

Project Description File: Always loaded (keep concise)
Skills: Load on demand (token efficient)
.toon mode: 95% token savings

项目描述文件：始终加载（需保持简洁）
Skills：按需加载（Token效率更高）
.toon模式：节省95% Token