agent-configuration

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

AI 에이전트 설정 정책 (Configuration & Security)

AI Agent配置策略（Configuration & Security）

When to use this skill

何时使用此Skill

새 프로젝트에 AI 에이전트 환경 구축
프로젝트 설명 파일 작성 및 최적화
Hooks/Skills/Plugins 설정
보안 정책 수립
팀 설정 공유

为新项目构建AI Agent环境
项目说明文件编写与优化
Hooks/Skills/Plugins配置
安全策略制定
团队配置共享

1. 프로젝트 설명 파일 작성 정책

1. 项目说明文件编写策略

개요

概述

프로젝트 설명 파일(CLAUDE.md, README 등)은 AI를 위한 프로젝트 설명서입니다. AI 에이전트는 이 파일을 최우선으로 참고합니다.

项目说明文件（CLAUDE.md、README等）是面向AI的项目说明书。AI Agent会优先参考此文件。

자동 생성 (Claude Code)

自动生成（Claude Code）

bash

/init  # Claude가 코드베이스 분석 후 초안 생성

bash

/init  # Claude分析代码库后生成初稿

필수 섹션 구조

必需章节结构

markdown

undefined

markdown

undefined

Project: [프로젝트명]

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

작성 원칙: 간결함의 미학

编写原则：简洁之美

Bad (장황함):

markdown

Our authentication system is built using NextAuth.js, which is a
complete authentication solution for Next.js applications...
(5줄 이상의 설명)

Good (간결함):

markdown

undefined

反面示例（冗长）：

markdown

Our authentication system is built using NextAuth.js, which is a
complete authentication solution for Next.js applications...
(5行以上的说明)

正面示例（简洁）：

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

점진적 추가 원칙

渐进式添加原则

"처음에는 프로젝트 설명 파일 없이 시작하세요. 같은 말을 반복하게 되면 그때 추가하세요."

"一开始可以不用项目说明文件就启动。当你开始重复说同样的话时，再添加进去。"

2. Hooks 설정 정책 (Claude Code)

2. Hooks配置策略（Claude Code）

개요

概述

Hooks는 특정 이벤트에 자동으로 실행되는 셸 명령어입니다. AI의 가드레일 역할.

Hooks是在特定事件下自动执行的Shell命令，起到AI的防护栏作用。

Hook 이벤트 종류

Hook事件类型

Hook	실행 시점	사용 사례
`PreToolUse`	도구 실행 전	위험한 명령어 차단
`PostToolUse`	도구 실행 후	로그 기록, 알림 전송
`PermissionRequest`	권한 요청 시	자동 승인/거부
`Notification`	알림 시	외부 시스템 통합
`SubagentStart`	서브에이전트 시작	모니터링
`SubagentStop`	서브에이전트 종료	결과 수집

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

보안 Hooks 설정

安全Hooks配置

json

// ~/.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": "과도한 권한 설정 주의"
      }
    ]
  }
}

json

// ~/.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. Skills 설정 정책

3. Skills配置策略

Skills vs 기타 설정 비교

Skills与其他配置对比

기능	로딩 시점	주요 사용자	토큰 효율성
프로젝트 설명 파일	항상 로드	프로젝트 팀	낮음 (항상 로드)
Skills	필요 시 로드	AI 자동	높음 (온디맨드)
Slash Commands	사용자 호출 시	개발자	중간
Plugins/MCP	설치 시	팀/커뮤니티	다양함

功能	加载时机	主要用户	Token效率
项目说明文件	始终加载	项目团队	低（始终加载）
Skills	需要时加载	AI自动调用	高（按需加载）
Slash Commands	用户调用时	开发者	中等
Plugins/MCP	安装时	团队/社区	多样

선택 가이드

选择指南

항상 적용되어야 하는 규칙 → 프로젝트 설명 파일
특정 작업에만 필요한 지식 → Skills (토큰 효율적)
자주 쓰는 명령어 → Slash Commands
외부 서비스 연동 → Plugins / MCP

需始终应用的规则 → 项目说明文件
仅特定任务需要的知识 → Skills（Token高效）
常用命令 → Slash Commands
外部服务集成 → Plugins / MCP

커스텀 Skill 생성

自定义Skill创建

bash

undefined

bash

undefined

스킬 디렉토리 생성

创建Skill目录

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

SKILL.md 작성

编写SKILL.md

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

name: my-skill description: 나의 커스텀 스킬 platforms: [Claude, Gemini, ChatGPT]

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

name: my-skill description: 我的自定义Skill platforms: [Claude, Gemini, ChatGPT]

My Skill

When to use

특정 작업에 필요할 때

需要执行特定任务时

Instructions

첫 번째 단계
두 번째 단계 EOF

---

第一步
第二步 EOF

---

4. 보안 정책

4. 安全策略

금지 사항 (DO NOT)

禁止事项（DO NOT）

절대 금지

绝对禁止

호스트 시스템에서 무제한 권한 모드 사용
루트 디렉토리 삭제 명령어 자동 승인
```
.env
```
,
```
credentials.json
```
등 시크릿 파일 커밋
API 키 하드코딩

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

주의 필요

需要注意

```
sudo
```
명령어 무분별한 승인
```
curl | sh
```
형태의 스크립트 실행
```
chmod 777
```
과도한 권한 설정
알 수 없는 MCP 서버 연결

无节制地批准
```
sudo
```
命令
执行
```
curl | sh
```
形式的脚本
设置
```
chmod 777
```
过度权限
连接未知的MCP服务器

승인된 명령어 감사

批准命令审计

bash

undefined

bash

undefined

cc-safe 도구로 위험한 명령어 검사

使用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

undefined

undefined

안전한 자동 승인 (Claude Code)

安全自动批准（Claude Code）

bash

undefined

bash

undefined

안전한 명령어만 자동 승인

仅自动批准安全命令

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

패턴 승인

模式批准

/sandbox "git *" # git 명령어 전체 /sandbox "npm test *" # npm test 관련

/sandbox "git *" # 所有git命令 /sandbox "npm test *" # 所有npm test相关命令

MCP 도구 패턴

MCP工具模式

/sandbox "mcp__server__*"

---

/sandbox "mcp__server__*"

---

5. 팀 설정 공유

5. 团队配置共享

프로젝트 설정 구조

项目配置结构

project/
├── .claude/                    # Claude Code 설정
│   ├── team-settings.json
│   ├── hooks/
│   └── skills/
├── .agent-skills/              # 범용 스킬
│   ├── backend/
│   ├── frontend/
│   └── ...
├── CLAUDE.md                   # Claude용 프로젝트 설명
├── .cursorrules               # Cursor용 설정
└── ...

project/
├── .claude/                    # Claude Code配置
│   ├── team-settings.json
│   ├── hooks/
│   └── skills/
├── .agent-skills/              # 通用Skill
│   ├── backend/
│   ├── frontend/
│   └── ...
├── CLAUDE.md                   # 面向Claude的项目说明
├── .cursorrules               # Cursor配置
└── ...

team-settings.json 예시

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"]
    }
  }
}

팀 공유 워크플로우

团队共享工作流

.claude/ 폴더 커밋 → 팀원 Clone → 동일 설정 자동 적용 → 팀 표준 유지

提交.claude/目录 → 团队成员克隆 → 自动应用相同配置 → 维持团队标准

6. Multi-Agent 설정

6. Multi-Agent配置

에이전트별 설정 파일

各Agent配置文件

Agent	설정 파일	위치
Claude Code	CLAUDE.md, settings.json	프로젝트 루트, ~/.claude/
Gemini CLI	.geminirc	프로젝트 루트, ~/
Cursor	.cursorrules	프로젝트 루트
ChatGPT	Custom Instructions	UI 설정

Agent	配置文件	位置
Claude Code	CLAUDE.md, settings.json	项目根目录, ~/.claude/
Gemini CLI	.geminirc	项目根目录, ~/
Cursor	.cursorrules	项目根目录
ChatGPT	Custom Instructions	UI设置

공통 스킬 디렉토리

通用Skill目录

.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. 환경 설정 체크리스트

7. 环境配置检查清单

초기 설정

初始配置

프로젝트 설명 파일 생성 (
```
/init
```
또는 수동)
터미널 별칭 설정 (
```
c
```
,
```
cc
```
,
```
g
```
,
```
cx
```
)
외부 에디터 설정 (
```
export EDITOR=vim
```
)
MCP 서버 연결 (필요 시)

生成项目说明文件（
```
/init
```
或手动编写）
设置终端别名（
```
c
```
,
```
cc
```
,
```
g
```
,
```
cx
```
）
设置外部编辑器（
```
export EDITOR=vim
```
）
连接MCP服务器（如有需要）

보안 설정

安全配置

위험한 명령어 Hooks 설정
승인된 명령어 목록 점검 (
```
cc-safe
```
)
.env 파일 .gitignore 확인
컨테이너 환경 준비 (실험용)

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

팀 설정

团队配置

.claude/ 폴더 Git 커밋
team-settings.json 작성
팀 표준 프로젝트 설명 파일 템플릿

将.claude/目录提交至Git
编写team-settings.json
制定团队标准项目说明文件模板

Quick Reference

快速参考

설정 파일 위치

配置文件位置

~/.claude/settings.json     # 글로벌 설정
~/.claude/skills/           # 글로벌 스킬
.claude/settings.json       # 프로젝트 설정
.claude/skills/             # 프로젝트 스킬
.agent-skills/              # 범용 스킬
CLAUDE.md                   # 프로젝트 AI 설명서

~/.claude/settings.json     # 全局配置
~/.claude/skills/           # 全局Skill
.claude/settings.json       # 项目配置
.claude/skills/             # 项目Skill
.agent-skills/              # 通用Skill
CLAUDE.md                   # 项目AI说明书

보안 우선순위

安全优先级

1. Hooks로 위험 명령어 차단
2. /sandbox로 안전한 명령어만 자동 승인
3. cc-safe로 정기 감사
4. 실험 모드는 컨테이너에서만

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

토큰 효율성

Token效率

프로젝트 설명 파일: 항상 로드 (간결하게 유지)
Skills: 필요 시 로드 (토큰 효율적)
.toon 모드: 95% 토큰 절감

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