AI 에이전트의 코드베이스 오동작을 역추적하고 복구하는 방법
makedream30 июля 2026 г.
0
컴퓨터/소프트웨어Related Video
4:58Mindwalk: 전체 코드베이스를 3D 지도로 확인하세요
Better Stack
Comments (0)
Log in to leave a comment
No posts yet
makedream4:58makedream4:58Better Stack
Log in to leave a comment
No posts yet
10만 줄이 넘는 백엔드 레포지토리에 Claude Code나 Codex 같은 AI 에이전트를 붙여보면 처음엔 속도에 감탄한다. 그러다 어느 순간 프롬프트 몇 줄 잘못 들어가는 순간, AI는 경계망을 뚫고 나가 공통 유틸리티나 환경 설정 파일까지 건드려 놓는다. 세션 로그는 몇 메가바이트 단위로 불어나고, 빌드는 터지고, 원인 파일을 찾으려 Git Diff만 한 시간째 훑다 보면 차라리 내가 처음부터 짜는 게 나았겠다는 생각이 솟구친다.
에이전트에게 자율성을 주되 불필요한 파일 손상을 막으려면 명확한 하드 격리와 시각화된 트레이스 추적 체계가 필요하다.
자연어 지침 파일인 CLAUDE.md나 .aiignore는 컨텍스트 창이 길어지면 에이전트가 우회하기 일쑤다. 프롬프트 단계의 요청은 어디까지나 권장 사항일 뿐이라, 맥락을 놓치는 순간 에이전트 도구 실행이 거침없이 울타리를 넘어가버린다.
에이전트의 손길을 물리적으로 차단하려면 프로젝트 루트에 결정론적 권한 제어 엔진인 .claude/settings.json을 직접 배치해야 한다.
{
"permissions": {
"deny": [
"Edit(src/core/config/**)",
"Edit(src/shared/utils/**)",
"Read(./.env*)",
"Bash(rm -rf *)"
],
"ask": [
"Edit(src/api/v1/legacy/**)"
]
}
}
명시적 차단 규칙을 세운 뒤에는 파일 시스템 레벨에서도 한 번 더 잠가버리는 편이 안전하다. 프로덕션 빌드 스크립트나 보안 키 파일은 OS 차원에서 쓰기 권한을 빼앗아 두는 게 깔끔하다.
.claude/settings.json을 작성한다.permissions.deny 배열에 환경 설정, 공통 유틸리티 경로, 파괴적인 Bash 명령을 등록한다.chmod 444 .env* 명령으로 프로세스 쓰기 권한을 차단한다.이렇게 권한을 제어해두면 AI가 뜬금없이 공통 모듈을 수정해 발생하는 빌드 에러를 상당 부분 쳐낼 수 있다.
개발자 개인의 로컬 환경에만 세션 로그(.jsonl)를 두면 나중에 사이드 이펙트가 터졌을 때 원인 규명이 어렵다. PR을 올리는 시점에 세션 트레이스를 압축하여 검증하도록 GitHub Actions 워크플로우를 짠다.
name: AI Agent Session Audit & Risk Analysis
on:
pull_request:
types: [opened, synchronize]
jobs:
audit-session:
runs-on: ubuntu-latest
steps:
- name: Checkout Code
uses: actions/checkout@v4
with:
fetch-depth: 0
- name: Setup Mindwalk Telemetry Extractor
run: |
docker run --rm -v ${{ github.workspace }}:/workspace \
cosmtrek/mindwalk:v0.1.0 parse --log-dir=./.claude/sessions --out=telemetry.json
- name: Run Deterministic Repo Audit
id: repo_audit
run: |
curl -sSL https://github.com/aletheore/releases/download/v1.0/aletheore -o aletheore
chmod +x aletheore
./aletheore audit --telemetry=telemetry.json --max-allowed-depth=3
- name: Upload Mindwalk 3D Visual Artifact
uses: actions/upload-artifact@v4
with:
name: mindwalk-3d-trace-${{ github.event.pull_request.number }}
path: telemetry.json
Rust 기반의 분석 엔진이나 Tree-sitter를 엮어 에이전트의 스코프 이탈 여부를 검사하면 허용 범위를 벗어난 상위 모듈 수정 시 CI 빌드를 즉시 실패로 되돌릴 수 있다.
변경 위험도는 단순 코드 줄 수 대신 노드 연결도 중심으로 계산하는 방식이 유용하다.
여기서 는 수정된 파일 수이고, 는 변경된 노드들의 평균 3D 연결도이다. 임계치를 넘어가면 슬랙 알림으로 3D 시각화 지도 링크를 쏘도록 만들어 두면 리뷰어가 위험도를 곧바로 파악할 수 있다.
에이전트가 난장판을쳐 놓았을 때는 전체 커밋을 날리는 대신 타임라인을 추적해 오염된 파일만 선별 복구해야 한다. 오작동을 시작한 특정 시간대를 추출했다면 jq로 JSONL 로그에서 해당 시점의 프롬프트와 추론 경로를 뽑아낸다.
jq -c 'select(.timestamp >= "2026-07-11T14:20:00Z" and .timestamp <= "2026-07-11T14:25:00Z") |
{timestamp: .timestamp, prompt: .payload.prompt, tool_use: .payload.tool_use, thinking: .payload.thinking}' \
./.claude/sessions/session_abc123.jsonl
원인을 확인했으면 복구 작업은 다음 3단계로 나누어 진행한다.
git checkout <PRE_AI_COMMIT_SHA> -- src/legacy/broken_module.ts)git clean -fd -- src/unwanted_generated_dir/)이 방식을 쓰면 정상 작동하는 코드까지 날려버리는 불상사 없이 손상된 파일만 깔끔하게 주워 담을 수 있다.
모노레포 환경에서 노드가 수만 개로 늘어나면 시각화 툴 자체도 뻗는다. 브라우저가 느려지면 디버깅도 싫어진다. 불필요한 디렉터리를 렌더링 대상에서 덜어내려면 mindwalk.config.json 배제 필터를 확실하게 잡아줘야 한다.
{
"visualization": {
"excludePatterns": [
"**/node_modules/<strong>",
"</strong>/vendor/<strong>",
"</strong>/.git/<strong>",
"</strong>/dist/<strong>",
"</strong>/coverage/<strong>",
"</strong>/*.log",
"**/*.pb.go"
],
"maxDepth": 5,
"groupingStrategy": "directory-segmented"
}
}
마지막으로 시각화 파이프라인이나 분석 도구를 백그라운드 Docker 컨테이너로 띄울 때는 자원 할당량을 제약해야 로컬 IDE가 안 멈춘다.
mindwalk.config.json을 작성해 의존성 디렉터리 노드를 시각화 대상에서 배제한다.--cpus="1.5" 및 --memory="2g" 옵션을 지정한다.--nice=19 플래그를 달아 CPU 우선순위를 최하위로 낮춘다.