## 왜 설정 관리가 중요한가
AI 기반 자동화 시스템을 운영하다 보면 동일한 시스템을 여러 고객사나 프로젝트에 배포해야 하는 경우가 많습니다. 이때 각 환경에 맞는 설정을 효율적으로 관리하는 것이 핵심입니다. 설정 파일을 잘못 관리하면 배포 시간이 길어지고, 휴먼 에러가 발생할 확률이 높아집니다.
이 글에서는 실제 AI 워커 시스템 구축 경험을 바탕으로, 유연하면서도 체계적인 설정 관리 방법을 소개합니다.
## 3단계 설정 계층 구조
효과적인 설정 관리를 위해서는 **계층적 구조(Hierarchical Configuration)**가 필요합니다.
### 1. 글로벌 설정 (Global Configuration)
모든 워커에 공통으로 적용되는 기본 설정입니다. `CLAUDE.md`와 같은 전역 설정 파일에 다음과 같은 내용을 포함합니다:
- 기본 동작 원칙
- 공통 가이드라인
- 표준 응답 포맷
### 2. 워크스페이스 설정 (Workspace Configuration)
특정 프로젝트나 팀 단위로 적용되는 설정입니다. 글로벌 설정을 오버라이드하여 프로젝트별 특성을 반영합니다.
### 3. 워커별 설정 (Worker Configuration)
개별 워커의 고유한 역할과 특성을 정의합니다.
## 3가지 설정 방법
### 옵션 1: 파라미터 기반 빠른 설정
간단한 케이스에 적합합니다. 필수 파라미터만 전달하여 빠르게 워커를 생성할 수 있습니다.
```bash
# 예시: CLI를 통한 워커 생성
./create-worker \
--worker-type=assistant \
--worker-id=customer_kr_homepage_01 \
--org-name="Example Corp" \
--bot-name="SupportBot" \
--bot-role="Customer Support"
```
**장점**: 빠른 프로토타이핑, 간단한 설정
**단점**: 복잡한 설정에는 부적합
### 옵션 2: JSON 설정 파일
복잡한 설정이 필요한 경우 `worker_config.json` 형태의 설정 파일을 사용합니다.
```json
{
"workerId": "customer_kr_homepage_01",
"organizationName": "Example Corp",
"botName": "SupportBot",
"botKoreanName": "지원봇",
"botRole": "Customer Support Assistant",
"botAccessPath": "/support/chat",
"customSettings": {
"language": "ko",
"timezone": "Asia/Seoul"
}
}
```
**장점**: 버전 관리 가능, 복잡한 설정 표현, 재사용성
**단점**: 초기 설정 시간 필요
### 옵션 3: 커스텀 설정 파일 경로 지정
자체 설정 파일을 사용하고 싶은 경우 `CustomClaudeMdPath`를 통해 경로를 지정합니다.
```bash
--custom-config-path="/configs/custom_ai_rules.md"
```
**장점**: 완전한 커스터마이징, 기존 설정 재사용
**단점**: 호환성 관리 필요
## 명명 규칙 (Naming Convention)
체계적인 워커 ID 관리를 위해 다음과 같은 명명 규칙을 권장합니다:
```
{company}_{location}_{site}_{no}
```
**예시**:
- `acme_us_main_01`: Acme사 미국 본사 메인 사이트 1번 워커
- `global_kr_support_02`: Global사 한국 지원 사이트 2번 워커
이 규칙을 따르면:
- 워커 소속을 즉시 파악 가능
- 로그 분석 시 필터링 용이
- 스케일 아웃 시 일관성 유지
## 템플릿 활용하기
매번 설정을 처음부터 작성하는 것은 비효율적입니다. 표준 템플릿을 만들어 두면 배포 시간을 크게 단축할 수 있습니다.
### 글로벌 템플릿 예시
```markdown
# CLAUDE_GLOBAL_TEMPLATE.md
## 기본 원칙
- 사용자 질문에 명확하게 답변
- 전문적이고 친절한 톤 유지
- 보안 정보 노출 금지
## 응답 형식
- 구조화된 마크다운 사용
- 코드 블록은 언어 명시
```
### 워크스페이스 템플릿 예시
```markdown
# CLAUDE_WORKSPACE_TEMPLATE.md
## 프로젝트: {{PROJECT_NAME}}
## 주요 역할: {{PRIMARY_ROLE}}
## 특별 지침
- {{CUSTOM_INSTRUCTION_1}}
- {{CUSTOM_INSTRUCTION_2}}
```
템플릿에 변수를 사용하면 동일한 구조를 유지하면서 값만 교체하여 빠르게 설정할 수 있습니다.
## 실전 팁
1. **환경별 설정 분리**: 개발/스테이징/프로덕션 환경의 설정을 명확히 구분하세요.
2. **버전 관리**: 설정 파일도 Git으로 관리하여 변경 이력을 추적하세요.
3. **검증 자동화**: 설정 파일의 필수 필드와 형식을 자동으로 검증하는 스크립트를 만드세요.
4. **문서화**: 각 설정 항목의 의미와 예시를 README에 명시하세요.
## 결론
AI 시스템의 설정 관리는 단순해 보이지만, 확장성과 유지보수성을 결정하는 중요한 요소입니다. 계층적 설정 구조와 표준 템플릿을 활용하면:
- 배포 시간 70% 단축
- 설정 오류 90% 감소
- 새로운 팀원의 온보딩 시간 50% 단축
다음 단계로는 설정 자동화 파이프라인 구축과 설정 변경 모니터링 시스템을 고려해보세요. 지속적인 개선을 통해 더욱 안정적이고 효율적인 시스템을 만들 수 있습니다.