AI 에이전트의 코드베이스 오동작을 역추적하고 복구하는 방법

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가 뜬금없이 공통 모듈을 수정해 발생하는 빌드 에러를 상당 부분 쳐낼 수 있다.

CI/CD 파이프라인으로 세션 위험도 검증하기

개발자 개인의 로컬 환경에만 세션 로그(.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 빌드를 즉시 실패로 되돌릴 수 있다.

변경 위험도는 단순 코드 줄 수 대신 노드 연결도 중심으로 계산하는 방식이 유용하다.

Risk\ Score = (N_{files} \times 0.4) + (D_{nodes} \times 0.6)

여기서 $N_{files}$ 는 수정된 파일 수이고, $D_{nodes}$ 는 변경된 노드들의 평균 3D 연결도이다. 임계치를 넘어가면 슬랙 알림으로 3D 시각화 지도 링크를 쏘도록 만들어 두면 리뷰어가 위험도를 곧바로 파악할 수 있다.

타임스탬프 기반의 3구간 롤백

에이전트가 난장판을쳐 놓았을 때는 전체 커밋을 날리는 대신 타임라인을 추적해 오염된 파일만 선별 복구해야 한다. 오작동을 시작한 특정 시간대를 추출했다면 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단계로 나누어 진행한다.

1단계 파일 선택 복구: AI 투입 전 커밋을 기준으로 손상된 파일만 가져온다. (git checkout <PRE_AI_COMMIT_SHA> -- src/legacy/broken_module.ts)
2단계 생성 델타 제거: AI가 임의로 만들어낸 쓰레기 파일 및 오염된 설정 디렉터리를 지운다. (git clean -fd -- src/unwanted_generated_dir/)
3단계 세션 트레이스 잘라내기: 전체 코드를 에이전트 투입 전 SHA로 돌리고, JSONL 파일에서 문제가 발생한 타임스탬프 이후의 기록을 제거해 나쁜 맥락을 재학습하지 않게 세션을 셋업한다.

이 방식을 쓰면 정상 작동하는 코드까지 날려버리는 불상사 없이 손상된 파일만 깔끔하게 주워 담을 수 있다.

시각화 데이터 렌더링 최적화

모노레포 환경에서 노드가 수만 개로 늘어나면 시각화 툴 자체도 뻗는다. 브라우저가 느려지면 디버깅도 싫어진다. 불필요한 디렉터리를 렌더링 대상에서 덜어내려면 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 우선순위를 최하위로 낮춘다.

AI 에이전트의 코드베이스 오동작을 역추적하고 복구하는 방법

에이전트에게 자율성을 주되 불필요한 파일 손상을 막으려면 명확한 하드 격리와 시각화된 트레이스 추적 체계가 필요하다.

설정 파일 격리로 무단 수정 차단하기

에이전트의 손길을 물리적으로 차단하려면 프로젝트 루트에 결정론적 권한 제어 엔진인 .claude/settings.json을 직접 배치해야 한다.

{
  "permissions": {
    "deny": [
      "Edit(src/core/config/**)",
      "Edit(src/shared/utils/**)",
      "Read(./.env*)",
      "Bash(rm -rf *)"
    ],
    "ask": [
      "Edit(src/api/v1/legacy/**)"
    ]
  }
}

프로젝트 루트에 .claude/settings.json을 작성한다.
permissions.deny 배열에 환경 설정, 공통 유틸리티 경로, 파괴적인 Bash 명령을 등록한다.
터미널에서 chmod 444 .env* 명령으로 프로세스 쓰기 권한을 차단한다.

이렇게 권한을 제어해두면 AI가 뜬금없이 공통 모듈을 수정해 발생하는 빌드 에러를 상당 부분 쳐낼 수 있다.

CI/CD 파이프라인으로 세션 위험도 검증하기

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

변경 위험도는 단순 코드 줄 수 대신 노드 연결도 중심으로 계산하는 방식이 유용하다.

Risk\ Score = (N_{files} \times 0.4) + (D_{nodes} \times 0.6)

타임스탬프 기반의 3구간 롤백

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단계로 나누어 진행한다.

1단계 파일 선택 복구: AI 투입 전 커밋을 기준으로 손상된 파일만 가져온다. (git checkout <PRE_AI_COMMIT_SHA> -- src/legacy/broken_module.ts)
2단계 생성 델타 제거: AI가 임의로 만들어낸 쓰레기 파일 및 오염된 설정 디렉터리를 지운다. (git clean -fd -- src/unwanted_generated_dir/)
3단계 세션 트레이스 잘라내기: 전체 코드를 에이전트 투입 전 SHA로 돌리고, JSONL 파일에서 문제가 발생한 타임스탬프 이후의 기록을 제거해 나쁜 맥락을 재학습하지 않게 세션을 셋업한다.

이 방식을 쓰면 정상 작동하는 코드까지 날려버리는 불상사 없이 손상된 파일만 깔끔하게 주워 담을 수 있다.

시각화 데이터 렌더링 최적화

{
  "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 우선순위를 최하위로 낮춘다.

AI 에이전트의 코드베이스 오동작을 역추적하고 복구하는 방법

Related Video

Mindwalk: 전체 코드베이스를 3D 지도로 확인하세요

AI 에이전트의 코드베이스 오동작을 역추적하고 복구하는 방법

설정 파일 격리로 무단 수정 차단하기

CI/CD 파이프라인으로 세션 위험도 검증하기

타임스탬프 기반의 3구간 롤백

시각화 데이터 렌더링 최적화

Comments (0)

AI 에이전트의 코드베이스 오동작을 역추적하고 복구하는 방법

설정 파일 격리로 무단 수정 차단하기

CI/CD 파이프라인으로 세션 위험도 검증하기

타임스탬프 기반의 3구간 롤백

시각화 데이터 렌더링 최적화