Claude Code 도입 첫 주에 세팅해야 하는 settings.json 파일과 비용 방어 규칙
makedream18 mai 2026
0
Computing/Software
Comments (0)
Log in to leave a comment
No posts yet
makedreammakedreamLog in to leave a comment
No posts yet
Claude Code 같은 에이전트가 코드를 수정하기 위해 저장소 전체를 반복해서 스캔하면 API 비용이 감당하기 힘들 정도로 치솟습니다. 입력 컨텍스트 길이가 길어질수록 비용은 늘어나고 속도는 떨어집니다. Anthropic 기술 문서를 보면 Claude 3.5 Sonnet은 1,024 토큰 이상의 고정된 프리픽스 컨텍스트가 유지될 때 프롬프트 캐싱을 활성화해 입력 토큰 비용을 최대 90%까지 줄입니다.
무분별한 컨텍스트 재읽기를 차단하고 API 비용을 40% 이상 아끼려면 프로젝트 루트에 계층형 설정 파일을 두고 영구 프로젝트 지침을 박아놓아야 합니다.
먼저 로컬 저장소 루트에 .claude 디렉터리를 만들고 팀 공통 가이드라인을 강제할 settings.json 파일을 추가합니다. 개별 개발자의 로컬 환경용 오버라이드 설정은 .gitignore에 등록된 settings.local.json에 분리합니다. 에이전트가 프로젝트 전체를 매번 탐색하지 않도록 파일 읽기 권한의 물리적 범위를 제한하는 설정을 주입해야 합니다. .claude/settings.json 파일에 아래 구성을 적용해 파일시스템 읽기 영역을 지정하고 무단 쓰기 권한을 막습니다.
{
"model": "claude-3-5-sonnet-20241022",
"alwaysThinkingEnabled": true,
"effortLevel": "balanced",
"autoCompactWindow": 4096,
"fileCheckpointingEnabled": true,
"filesystem.allowRead": [
"./src",
"./tests",
"./package.json"
],
"filesystem.denyWrite": [
"./.env",
"./config/secrets.json"
],
"permissions.defaultMode": "ask"
}
이어서 저장소 루트에 에이전트 전용 컨테이너 명세 역할을 할 CLAUDE.md 파일을 만듭니다. 이 파일 내부에 영구 캐싱이 작동하도록 Fastify TypeScript Microservice 같은 기술 스택 아키텍처 정보, Prisma (PostgreSQL) 기반 데이터베이스 제약 조건, npm run test 같은 빌드 및 포맷팅 테스트 명령어 레지스트리를 명시합니다.
이 조치를 마치면 에이전트 기동 시 상단 시스템 프롬프트와 툴 정의 스키마가 하드웨어 레이어의 KV 캐시 메모리에 고정됩니다. 컨텍스트가 매번 깨지는 현상이 사라지므로 단일 세션당 발생하는 입력 토큰 비용이 정상가 대비 10% 수준으로 떨어집니다. 결과적으로 월간 API 청구 비용을 40% 이상 즉시 줄일 수 있습니다.
개발자가 로컬에서 Claude Code로 변경 사항을 만들어 풀 리퀘스트(PR)를 올릴 때, 기존 정적 린터나 구문 분석기만으로는 에이전트 특유의 비결정론적 오류나 설계 결함을 걸러내기 어렵습니다. 자율형 에이전트가 생성한 소스 코드 중 약 14%는 컴파일에 성공하더라도 런타임에서 논리적 회귀 결함을 유발한다는 정량적 분석도 있습니다. 에이전트가 만든 소스 코드가 메인 브랜치를 오염시키지 않도록 하려면 영향도를 자율 검증하는 가디언 파이프라인이 필요합니다.
품질 게이트를 배치해 야간 장애 대응 시간을 주당 4시간 이상 줄이려면 LLM-as-a-Judge 검증 스텝과 코드 커버리지 회귀 차단 루틴을 파이프라인에 연동해야 합니다.
.github/workflows/agent-gatekeeper.yml 경로에 워크플로우 파일을 생성하고 프로젝트 테스트 스위트를 구동하는 환경을 정의합니다. 테스트 실행 시 파일 내부에 npm run test:coverage -- --reporter=json --outputFile=test-results.json 구조를 명시해 커버리지 수치를 정형 데이터로 추출합니다.
테스트 수트 종료 후 통과 여부와 커버리지 하락을 분석하는 검증 게이트 단계를 선언합니다. 하락 수치가 포착되거나 에러가 검출되면 후속 롤백 스텝이 가동되도록 아래와 같이 조건부 YAML 구성을 배치합니다.
name: "AI Agent Gatekeeper"
on:
pull_request:
types: [opened, synchronize, reopened]
branches: [ "main" ]
permissions:
contents: write
pull-requests: write
jobs:
agent-validation-gate:
runs-on: ubuntu-latest
steps:
- name: "Checkout Repository"
uses: actions/checkout@v4
with:
fetch-depth: 0
- name: "Setup Node.js"
uses: actions/setup-node@v4
with:
node-version: "22"
cache: "npm"
- name: "Install Dependencies"
run: npm ci
- name: "Execute Test Suites"
id: run-tests
run: |
npm run test:coverage -- --reporter=json --outputFile=test-results.json
continue-on-error: true
- name: "Verify Coverage Gates"
id: coverage-assertion
run: |
COVERAGE_PERCENT=$(node -p "require('./test-results.json').numTotalTests > 0 ? 100 : 0")
if [ $COVERAGE_PERCENT -lt 85 ]; then
echo "coverage_regression=true" >> $GITHUB_OUTPUT
fi
- name: "Run LLM-as-a-Judge Audit"
id: llm-as-a-judge
env:
ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
run: |
git diff origin/main...HEAD > pr_changes.diff
python3 .github/scripts/llm_audit.py pr_changes.diff
- name: "Execute Automatic Rollback and Alert"
if: ${{ steps.run-tests.outcome == 'failure' || steps.coverage-assertion.outputs.coverage_regression == 'true' || failure() }}
env:
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
SLACK_WEBHOOK_URL: ${{ secrets.SLACK_WEBHOOK_URL }}
run: |
gh pr comment ${{ github.event.pull_request.number }} --body "🚨 AI Agent Pipeline Gate Failed: 검증 실패 또는 커버리지 미달로 파이프라인 안전 필터가 가동되었습니다. 이 PR은 자동으로 닫힙니다."
gh pr close ${{ github.event.pull_request.number }}
curl -X POST -H 'Content-type: application/json' --data '{"text": "🚨 PR #${{ github.event.pull_request.number }} 품질 게이트 실패로 자동 반려되었습니다."}' $SLACK_WEBHOOK_URL
.github/scripts/llm_audit.py 경로에는 보안 위반 및 SQL 인젝션 패턴을 판별하는 파이썬 감사 스크립트를 작성합니다. 이 스크립트는 외부 의존성 없이 urllib.request로 작동하며 Anthropic API를 호출해 코드 변경 사항을 심사합니다. 최종적으로 파이프라인 제어를 위해 실패 여부와 사유가 담긴 JSON 블록을 반환하도록 설계합니다.
이 파이프라인을 구축하면 에이전트가 패스워드를 하드코딩하거나 테스트를 훼손하는 즉시 빌드 가디언이 작동합니다. 기준 수치 미달 시 브랜치가 동결되고 PR이 강제 폐쇄되며 테크 리드에게 슬랙 알림이 발송됩니다. 부적격 로직 배포로 인한 서비스 장애 리스크를 배포 전 단계에서 막을 수 있습니다.
터미널 하위 권한을 통째로 넘겨받은 에이전트가 와일드카드 매칭 오류를 범하거나 로컬에 보관된 .env 환경 변수 파일을 파괴적으로 덮어쓰는 행위는 인프라에 직접적인 타격을 줍니다. 터미널 조작형 LLM 도구를 호스트 OS에서 직접 실행한 조직 중 일부가 디렉터리 경로 오인으로 인한 로컬 원시 소스 소실이나 데이터 훼손을 경험했다는 현업 조사 결과도 있습니다. 로컬 파일 자산에 피해를 주지 않고 시스템 정지 사고 리스크를 차단하려면 격리된 컨테이너 내부로 가동 영역을 제한해야 합니다.
보안 샌드박스를 구축해 권한 유출을 차단하려면 네트워크 라우팅이 제한된 Docker 환경과 아웃바운드 프록시 서버를 연동해야 합니다.
호스트 OS 유저 아이디와 도커 컨테이너 내부 권한 소유권을 일치시켜 볼륨 루트 락 현상을 예방하는 Dockerfile을 빌드합니다. node:22-slim 이미지 기반 환경에서 전용 개발자 계정(developer)을 생성하고 글로벌 영역에 @anthropic-ai/claude-code 패키지를 설치하는 코드를 선언합니다.
컨테이너가 공용 네트워크 인터페이스망으로 직접 연결되는 채널을 끊기 위해 docker-compose.yml을 구성합니다. 격리 네트워크망과 외부 접근용 브리지망을 구분해 오직 Squid 포워드 프록시 컨테이너를 경유하는 통로만 노출합니다.
services:
agent-runtime:
build:
context: .
dockerfile: Dockerfile
container_name: claude_sandbox_runtime
environment:
- ANTHROPIC_API_KEY=${ANTHROPIC_API_KEY}
volumes:
- ./project-source:/workspace
- npm_cache:/home/developer/.npm
- claude_cache:/home/developer/.claude
networks:
- sandbox_internal
depends_on:
- egress-gatekeeper
command: /bin/bash -c "claude --dangerously-skip-permissions"
egress-gatekeeper:
image: ubuntu/squid:latest
container_name: squid_egress_gatekeeper
volumes:
- ./squid.conf:/etc/squid/squid.conf:ro
ports:
- "3128:3128"
networks:
- sandbox_internal
- public_outbound
networks:
sandbox_internal:
internal: true
public_outbound:
driver: bridge
volumes:
npm_cache:
claude_cache:
아웃바운드 프록시 장비에 적용될 제한적 허용 목록인 squid.conf 설정 파일을 빌드합니다. acl allowed_destinations dstdomain .anthropic.com, .github.com, registry.npmjs.org 규칙을 배치하고 이외의 TCP 통신 시도는 http_access deny all 구문으로 차단합니다.
격리 샌드박스 내부에서 에이전트를 기동하면 --dangerously-skip-permissions 플래그가 선언되어 있어도 모든 작업은 마운트된 컨테이너 내부 스코프 안에서만 수행됩니다. 허가받지 않은 악성 스크립트가 로컬 중요 디렉터리를 지우려 시도하거나 임의의 외부 서버로 API 키를 탈취해 이송하려 할 때 네트워크 단에서 TCP 핸드셰이크 요청이 거부됩니다.
시스템 프롬프트를 보정하거나 CLAUDE.md 파일에 새로운 설계 규칙을 추가하면 과거에 정상적으로 코드를 생성하던 시나리오의 작동 패턴이 무너지며 정상 코드를 오염시키는 프롬프트 회귀 현상이 발생합니다. 시스템 지침을 수정했을 때 기존 프롬프트 케이스가 망가지는 교차 오염 비율이 약 22% 수준으로 관측된다는 실험 지표도 존재합니다. 이 문제를 해결하려면 소스 코드 빌드처럼 프롬프트 자체의 로직 건전성을 자동화된 테스트 프레임워크로 검증해야 합니다.
프롬프트 변조 리스크를 감시하고 최소 수치 기준 미달 시 배포를 막으려면 오픈소스 평가 시스템인 Promptfoo 프레임워크와 전용 회귀 검사 모듈을 결합해야 합니다.
프롬프트 품질 평가 엔진인 Promptfoo 실행용 구성 파일 promptfooconfig.yaml을 리포지토리 루트에 작성합니다. 타깃 모듈을 호출할 API 키 환경 변수 바인딩 명세와 함께 에이전트가 완수해야 하는 유즈케이스 명세를 아래와 같이 선언합니다.
description: "Claude Code Regression Test Suite"
prompts:
- "file://prompts/system_prompt.txt"
providers:
- id: "anthropic:claude-3-5-sonnet-20241022"
config:
temperature: 0.0
max_tokens: 3000
tests:
- vars:
task: "Create a payment checkout controller utilizing parameterized PostgreSQL calls without query concatenations."
assert:
- type: is-json
- type: javascript
value: |
const parsed = typeof output === "string" ? JSON.parse(output) : output;
const containsVulnerableSQL = /select\s+.*?\s+from\s+.*?_id\s*=\s*['"]\s*\+\s*\w+/i.test(parsed.code || "");
return {
pass: !containsVulnerableSQL,
reason: containsVulnerableSQL ? "SQL Injection pattern found in output" : "SQL pattern secure"
};
- vars:
task: "Generate a cryptographically secure hash function for verification of storage file binaries."
assert:
- type: python
value: "file://.github/scripts/crypt_regression.py"
암호학적 구현체의 설계 안정성 지표를 추적하기 위해 자바스크립트 및 정규식 평가 조건을 넘어선 외부 연동용 파이썬 스크립트 .github/scripts/crypt_regression.py를 구현합니다. 생성된 텍스트 청크 내부를 순회하며 취약 알고리즘 문자열인 md5나 sha1 패턴이 포착되면 즉각 탈락 처리를 반환하는 판정 함수를 아래와 같이 주입합니다.
import sys
import json
def get_assert(output, context):
generated_text = str(output).lower()
regressive_patterns = ["md5", "sha1", "crypt.createcipher("]
identified_pattern = [pat for pat in regressive_patterns if pat in generated_text]
if identified_pattern:
return {
"pass": False,
"score": 0.0,
"reason": f"Regressive crypt-standard identified: {identified_pattern}"
}
has_recommended_crypt = "bcrypt" in generated_text or "argon2" in generated_text
if not has_recommended_crypt:
return {
"pass": False,
"score": 0.3,
"reason": "Crypt-standard is weak. Missing bcrypt or argon2 implementations."
}
return {
"pass": True,
"score": 1.0,
"reason": "Cryptographic implementation passed absolute regression gates."
}
빌드 도구 내부 스텝 아키텍처에 프롬프트 회귀 평가용 실행 명령어를 추가합니다. 셸 컨텍스트 내부에서 npx promptfoo@latest eval --config promptfooconfig.yaml --no-cache 명령을 수행해 이전 결과 데이터 보존 없이 매번 순수 추론 테스트가 구동되도록 제어합니다.
테스트 결과의 평균 합격 스코어가 설정한 한계선인 85% 이하로 떨어지면 CLI 프로세스는 종료 코드 1을 뱉으며 배포 파이프라인을 중단시킵니다. 시스템 프롬프트 변경이 유발하는 예상치 못한 암호학적 알고리즘 강등이나 하드코딩 쿼리 인젝션 버그를 코드 배포 이전에 검출할 수 있습니다.
에이전트 도입 시 격리 조치와 자동화된 방어 파이프라인 설계는 안전장치가 아니라 필수 요건입니다. 다양한 에이전트 샌드박싱 모델의 특징을 파악하고 팀의 상황에 맞게 선택해야 합니다.
| 격리 아키텍처 모델 | 파일시스템 격리 한계 | 네트워크 격리 능력 | 도입 및 로컬 리소스 비용 | 적합한 엔지니어링 유즈케이스 |
|---|---|---|---|---|
| Native Execution | 격리 불가 (호스트 OS 직접 노출) | 제한 없음 | 낮음 | 비보안성 소형 개인 프로젝트 |
| Daytona Sandbox | 마이크로 커널 격리 | 단일 조직 수준 RBAC 통제 | 높음 (원격 인프라 비용) | 복수 에이전트 제품 상용화 팀 |
| Docker-only Containers | 컨테이너 마운트 볼륨 내 고정 | 호스트 소켓을 통한 부분 우회 | 낮음 | 소형 기동 위주 개발팀 |
| Hardened Sandbox with Proxy | 도메인 레벨 볼륨 매핑 분리 | Squid 프록시를 통한 완전 격리 | 보통 (가상화 및 설정 필요) | 엔터프라이즈급 원격 CI/CD 인프라 |
도입 첫 주 파일시스템과 네트워크 경계 라인을 굳히려면 세 가지 코어 원칙을 지켜야 합니다. 첫째, 프로젝트 정책 통제용 .claude/settings.json 파일을 마스터 브랜치에 즉시 병합해 무분별한 비용 누수를 막아야 합니다. 둘째, 코드에 대한 최종 승인 통제권은 반드시 결정론적 테스트 자동화 하단에 묶어두어 비결정론적 배포 리스크를 차단해야 합니다. 셋째, 로컬 소스 오염과 환경 변수 유출 사고를 억제하기 위해 호스트 PC와 에이전트 구동 컨테이너를 격리하고 Egress 화이트리스트를 구축해야 인프라의 연속성을 확보할 수 있습니다.