설정 파일

Claude Code는 프로젝트별 설정 파일을 통해 동작을 세밀하게 제어할 수 있습니다. 프로젝트 루트에 .claude 파일을 생성하여 설정을 관리합니다.

기본 설정 파일 구조

.claude 파일은 JSON 형식으로 작성되며, 다양한 옵션을 포함할 수 있습니다.

{
  "version": "1.0",
  "model": "claude-3-opus",
  "language": "ko",
  "tools": {
    "allowed": ["read", "write", "bash", "grep"],
    "disallowed": ["webSearch"]
  },
  "files": {
    "exclude": [
      "node_modules/**",
      "dist/**",
      "*.min.js"
    ],
    "include": [
      "src/**",
      "tests/**"
    ]
  }
}

주요 설정 옵션

모델 설정

{
  "model": "claude-3-opus",
  "modelOptions": {
    "temperature": 0.7,
    "maxTokens": 4096,
    "topP": 0.9
  }
}
  • model: 사용할 Claude 모델 지정
  • temperature: 응답의 창의성 수준 (0.0-1.0)
  • maxTokens: 최대 응답 길이
  • topP: 누적 확률 임계값

도구 권한 설정

{
  "tools": {
    "allowed": [
      "read",
      "write",
      {
        "name": "bash",
        "commands": ["npm test", "npm run"]
      }
    ],
    "requireConfirmation": ["write", "bash"],
    "timeout": 30000
  }
}

파일 필터링

{
  "files": {
    "exclude": [
      "**/*.log",
      "**/*.tmp",
      ".git/**",
      "coverage/**"
    ],
    "include": [
      "src/**/*.{js,ts,jsx,tsx}",
      "tests/**/*.test.js"
    ],
    "maxFileSize": "2MB",
    "followSymlinks": false
  }
}

프로젝트별 커스터마이징

React 프로젝트 예제

{
  "version": "1.0",
  "projectType": "react",
  "conventions": {
    "componentStyle": "functional",
    "stateManagement": "hooks",
    "styling": "styled-components"
  },
  "codeStyle": {
    "quotes": "single",
    "semicolons": true,
    "indentSize": 2
  },
  "testing": {
    "framework": "jest",
    "coverageThreshold": 80
  }
}

Python 프로젝트 예제

{
  "version": "1.0",
  "projectType": "python",
  "python": {
    "version": "3.11",
    "packageManager": "poetry",
    "linter": "ruff",
    "formatter": "black"
  },
  "tools": {
    "allowed": [
      "read",
      "write",
      {
        "name": "bash",
        "commands": ["poetry run", "pytest"]
      }
    ]
  }
}

고급 설정

커스텀 명령어

{
  "customCommands": {
    "deploy": {
      "description": "프로덕션 배포",
      "steps": [
        "npm test",
        "npm run build",
        "npm run deploy:prod"
      ]
    },
    "review": {
      "description": "코드 리뷰 실행",
      "prompt": "코드 스타일 가이드에 따라 리뷰해주세요"
    }
  }
}

환경별 설정

{
  "environments": {
    "development": {
      "tools": {
        "allowed": ["*"]
      }
    },
    "production": {
      "tools": {
        "allowed": ["read", "grep"],
        "disallowed": ["write", "bash"]
      },
      "readOnly": true
    }
  }
}

보안 설정

{
  "security": {
    "sensitiveFiles": [
      ".env",
      "**/*.key",
                "**/*.pem"
    ],
    "redactPatterns": [
      "API_KEY=.*",
      "PASSWORD=.*"
    ],
    "requireAuth": true,
    "allowedUsers": ["user@example.com"]
  }
}

템플릿과 스니펫

{
  "templates": {
    "component": {
      "path": "templates/react-component.js",
      "variables": ["componentName", "props"]
    },
    "test": {
      "path": "templates/jest-test.js"
    }
  },
  "snippets": {
    "api-endpoint": "snippets/api-endpoint.js",
    "error-handler": "snippets/error-handler.js"
  }
}

설정 상속과 오버라이드

Claude Code는 여러 레벨의 설정 파일을 지원합니다:

  1. 전역 설정: ~/.claude/config.json
  2. 프로젝트 설정: project/.claude
  3. 디렉토리 설정: subdir/.claude
  4. 환경 변수
  5. 명령줄 옵션

📝 우선순위

하위 레벨의 설정이 상위 레벨을 오버라이드합니다. 명령줄 옵션이 가장 높은 우선순위를 가집니다.

설정 검증

설정 파일이 올바른지 확인하는 명령어:

# 설정 파일 검증
claude validate-config

# 현재 적용된 설정 확인
claude config --show

# 설정 파일 생성 도우미
claude init

모범 사례

💡 설정 파일 관리 팁

  • 민감한 정보는 환경 변수로 관리
  • 팀 프로젝트는 공통 설정 파일 사용
  • .claude 파일을 버전 관리에 포함
  • 환경별로 다른 설정 파일 사용 고려
  • 주기적으로 설정 검토 및 업데이트

다음 단계

다음 보안 →