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

When to use this skill

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

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

개요

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

자동 생성 (Claude Code)

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

필수 섹션 구조

# Project: [프로젝트명]

## Tech Stack
- **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

## DO NOT
- 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

작성 원칙: 간결함의 미학

Bad (장황함):

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

Good (간결함):

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

점진적 추가 원칙

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

2. Hooks 설정 정책 (Claude Code)

개요

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

Hook 이벤트 종류

보안 Hooks 설정

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

Skills vs 기타 설정 비교

선택 가이드

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

커스텀 Skill 생성

# 스킬 디렉토리 생성
mkdir -p ~/.claude/skills/my-skill

# SKILL.md 작성
cat > ~/.claude/skills/my-skill/SKILL.md << 'EOF'
---
name: my-skill
description: 나의 커스텀 스킬
platforms: [Claude, Gemini, ChatGPT]
---

# My Skill

## When to use
- 특정 작업에 필요할 때

## Instructions
1. 첫 번째 단계
2. 두 번째 단계
EOF

4. 보안 정책

금지 사항 (DO NOT)

절대 금지

• 호스트 시스템에서 무제한 권한 모드 사용
• 루트 디렉토리 삭제 명령어 자동 승인
• .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 'Team hook: validating...'"]
    }
  },
  "mcpServers": {
    "company-db": {
      "command": "npx",
      "args": ["@company/db-mcp"]
    }
  }
}

팀 공유 워크플로우

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

6. Multi-Agent 설정

에이전트별 설정 파일

공통 스킬 디렉토리

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

7. 환경 설정 체크리스트

초기 설정

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

보안 설정

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

팀 설정

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

Quick Reference

설정 파일 위치

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

보안 우선순위

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

토큰 효율성

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