AI 에이전트 스크래치패드(Scratchpad): Git을 오염시키지 않고 코딩 에이전트의 속도를 유지하는 방법

코딩 에이전트(Coding agents)는 당신이 알아차리기도 전에 난장판을 만들 정도로 빠릅니다. 단 한 번의 프롬프트(prompt)만으로도 디버그 스크립트, JSON 덤프, 미완성된 노트, 복사된 스택 트레이스(stack traces), 그리고 마치 그 자리에 원래 있었던 것처럼 프로덕션 코드 옆에 자리 잡은 헬퍼 파일들을 남길 수 있습니다.

위험한 부분은 난장판 그 자체가 아닙니다. 진짜 위험한 부분은 그 난장판이 보이지 않게 될 때입니다. 소음이 심한 git status는 당신이 변경 사항을 무시하도록 길들여지게 만들고, 숨겨진 .gitignore 규칙은 유용한 에이전트 컨텍스트(context)를 에디터에서 사라지게 만들 수 있습니다. 만약 당신이 AI 지원 제품을 만든다면, 더 나은 패턴이 필요합니다. 에이전트가 자유롭게 사용할 수 있고, Git은 안전하게 무시할 수 있으며, 리뷰어가 추측 없이 정리할 수 있는 가시적인 스크래치패드(scratchpad)가 필요합니다.

이 가이드는 실제 개발 작업을 위한 AI 에이전트 스크래치패드를 설계하는 방법을 보여줍니다.

왜 지금 에이전트 스크래치패드가 중요한가

최근의 AI 개발 도구(developer tooling)는 동일한 방향으로 움직이고 있습니다. 에이전트들은 더 오래 실행되고, 더 많은 도구(tool)를 인식하며, 레포지토리(repos), Slack, 이슈 트래커(issue trackers), 브라우저, 그리고 로컬 파일과 더 깊게 연결되고 있습니다. 이는 유용합니다. 또한 임시 작업이 더 이상 인간만의 습관이 아니라는 것을 의미합니다.

에이전트는 다음과 같은 것들을 생성할 수 있습니다:

• 일회성 재현 스크립트 (one-off reproduction scripts)
• API 응답 덤프 (API response dumps)
• 벤치마크 출력값 (benchmark outputs)
• 마이그레이션 초안 (migration drafts)
• 스크린샷 또는 UI 노트
• 로컬 테스트 픽스처 (local test fixtures)
• 프롬프트 실험 (prompt experiments)
• 실패한 구현 시도
• 읽은 파일들의 요약

이 중 어느 것도 메인 소스 트리(source tree)에 영구적으로 머물러서는 안 됩니다. 어떤 것은 리뷰에 가치가 있고, 어떤 것은 민감하며, 어떤 것은 순전한 쓰레기입니다. 의도적인 스크래치패드가 없다면, 이 모든 것들은 프로젝트 전반에 흩어지게 됩니다.

핵심 문제는 간단합니다:

에이전트는 생각하고, 테스트하고, 증거를 수집할 공간이 필요합니다. 프로덕션 레포지토리(Production repos)는 깨끗한 경계가 필요합니다.

스크래치패드는 양쪽 모두에게 필요한 것을 제공합니다.

나쁜 패턴: 도처에 널린 무작위 임시 파일들

대부분의 팀은 기본 패턴으로 시작합니다. 에이전트가 원하는 곳 어디든 쓰게 내버려 둔 다음, 커밋(commit)하기 전에 정리하는 방식입니다.

이 방식은 아주 작은 작업에는 효과적입니다. 하지만 에이전트가 더 큰 워크플로우(workflows)를 처리할 때는 무너집니다.

실패하는 결제 동기화(billing sync)를 디버깅하는 코딩 에이전트를 상상해 보세요. 에이전트는 다음과 같은 파일들을 생성합니다:

scripts/test_sync.py
response.json
notes.md
...

나중에 사람이 돌아와서 확인하면 관련 없는 변경 사항들이 벽처럼 쌓여 있는 것을 보게 됩니다. 어떤 파일은 실제 파일이고, 어떤 파일은 실험용이며, 어떤 파일은 고객 데이터와 유사한 테스트 데이터를 포함하고 있습니다. 또 어떤 파일은 수정 사항을 이해하는 데 꼭 필요하기도 합니다.

이제 리뷰 품질이 떨어지게 됩니다. 리뷰어가 다음과 같은 기본적인 질문들을 던져야 하기 때문입니다:

• 이 파일이 기능(feature)의 일부인가?
• 이 파일은 에이전트가 생성한 것인가?
• 삭제해도 되는가?
• 비밀 정보(secrets)나 개인 데이터가 포함되어 있는가?
• 에이전트가 실수로 공유된 무시 규칙(ignore rules)을 변경했는가?
• 왜 디프(diff)가 이렇게 지저분한가?

엉망이 된 저장소(repo)는 단순히 시간만 낭비하는 것이 아닙니다. AI 워크플로우(workflow)에 대한 신뢰를 약화시킵니다.

더 나은 패턴: 로컬에서 확인 가능하며 무시되는 스크래치패드(Scratchpad)

좋은 에이전트 스크래치패드는 세 가지 속성을 가집니다:

1. **사람과 AI 도구 모두에게 가시적(Visible)**이어야 파일들을 참조, 검사 및 재사용할 수 있습니다.
2. **로컬 Git에서 무시(Ignored)**되어 임시 파일들이 커밋(commit)을 어지럽히지 않아야 합니다.
3. **목적에 따라 구조화(Structured)**되어 정리와 리뷰가 예측 가능해야 합니다.

중요한 세부 사항은 '로컬 무시(local ignore)'입니다. 공유되는 .gitignore 규칙을 추가하는 대신, .git/info/exclude를 사용하세요.

.git/info/exclude는 .gitignore처럼 동작하지만, 오직 사용자의 로컬 클론(local clone)에만 적용됩니다. 팀원, CI, 또는 공유 저장소에는 영향을 주지 않습니다.

이 점이 에이전트의 스크래치 작업(scratch work)에 이상적인 이유입니다.

권장되는 폴더 구조

temp/, scratch/, 또는 .agent-scratch/와 같은 하나의 최상위 디렉토리를 사용하세요. 저는 명확하고 짧은 temp/를 선호합니다.

실용적인 레이아웃은 다음과 같습니다:

temp/
  README.md
  scripts/
...

각 하위 폴더는 역할이 있습니다:

폴더	용도
scripts/	일회성 디버깅 및 마이그레이션 도우미
...

에이전트는 가시적인 관례(conventions)를 따르기 때문에 구조가 중요합니다. 스크래치패드가 파일들을 어디에 두어야 하는지 설명해 준다면, 에이전트가 저장소 곳곳에 파일을 흩뿌릴 가능성이 줄어듭니다.

스크래치패드 수동 설정하기

특별한 도구가 필요하지 않습니다. 일반적인 Git과 몇 가지 셸(shell) 명령만으로 이 패턴을 만들 수 있습니다.

mkdir -p temp/{scripts,dumps,drafts,traces,fixtures,screenshots,review-notes}
cat > temp/README.md <<'EOF'
# Local AI Scratchpad
...

이제 temp/ 디렉토리는 에디터에서 계속 보이지만, git status에는 나타나지 않습니다.

확인해 보세요:

git status --short

스크래치패드가 나타나지 않는다면, 로컬 제외(local exclude)가 제대로 작동하고 있는 것입니다.

에이전트 지침(Agent Instructions) 추가하기

스크래치패드는 에이전트가 이를 어떻게 사용하는지 알고 있을 때만 작동합니다. 저장소의 에이전트 가이드 파일에 짧은 지침을 추가하세요. 사용하는 도구에 따라 AGENTS.md, CLAUDE.md, .cursorrules 또는 다른 프로젝트 지침 파일이 될 수 있습니다.

예시:

## AI Scratchpad

임시 스크립트, 로그, API 덤프(dumps), 트레이스(traces), 초안(drafts) 등을 위해 `temp/`를 사용하세요.
...

이 작은 코드 블록 하나가 예상치 못한 엄청난 양의 파일 혼란을 방지합니다. 또한 리뷰어에게 증거를 찾을 수 있는 안정적인 장소를 제공합니다.

스크래치패드에 무엇을 넣어야 할까요?

작업을 해결하는 데 도움이 되지만, 기본적으로 커밋(commit)해서는 안 되는 작업에 스크래치패드를 사용하세요.

좋은 스크래치패드 후보:

• 버그를 한 번 재현하기 위한 스크립트
• 로컬 API로부터 받은 curl 응답
• 모델 출력 비교
• 빠른 벤치마크(benchmark) 결과
• 임시 SQLite 데이터베이스
• UI 확인을 위한 브라우저 스크린샷
• 제3자 SDK를 조사하며 작성한 노트
• 리뷰어가 이해하고 싶어 할 수도 있는 실패한 접근 방식

나쁜 스크래치패드 후보:

• 프로덕션 코드 (production code)
• 실제 마이그레이션(migration) 파일
• 커밋된 테스트 픽스처 (test fixtures)
• 비밀 정보 (secrets)
• .env 파일
• 사용자 내보내기 (user exports)
• 개인 고객 데이터
• CI가 반드시 읽어야 하는 파일
• 앱이 런타임(runtime)에 임포트(import)하는 모든 것

유용한 규칙:

앱이 그것을 필요로 한다면, 스크래치패드에 속하지 않습니다. 리뷰어가 그것을 필요로 할 수도 있다면, 속할 수 있습니다.

파일을 의도적으로 승격시키기

때때로 스크래치패드 파일이 실제 작업 결과물이 되기도 합니다. 디버그 스크립트가 회귀 테스트(regression test)가 되고, 초안 스키마(schema)가 마이그레이션이 되며, 임시 픽스처가 안정적인 테스트 픽스처가 됩니다.

그것은 괜찮습니다. 승격(promotion)은 명시적이어야 합니다.

파일을 temp/ 디렉토리 밖으로 이동하기 전에, 네 가지 질문을 던지세요:

1. 이 파일이 제품, 테스트, 문서 또는 운영을 장기적으로 지원하는가?
2. 비밀 정보(secrets)나 개인 데이터가 포함되어 있지 않은가?
3. 파일 이름이 향후 유지보수자들에게 충분히 명확한가?
4. 에이전트의 실험 과정에서 발생한 일회성 가정(throwaway assumptions)을 제거했는가?

승격 흐름 예시:

# 임시 재현 스크립트로부터
mv temp/scripts/repro-billing-sync.ts tests/regression/billing-sync-retry.test.ts

...

에이전트가 생성한 파일을 추적 대상 폴더(tracked folders)로 맹목적으로 이동하지 마세요. 스크래치패드 승격(scratchpad promotion)을 코드 리뷰(code review)처럼 취급하세요.

정리 명령(Cleanup Command) 추가하기

결코 정리되지 않는 스크래치패드는 잡동사니 서랍이 됩니다. 개발자와 에이전트에게 안전한 정리 명령을 제공하세요.

scripts/clean-scratchpad.sh를 생성하세요:

#!/usr/bin/env bash
set -euo pipefail

...

만약 팀에서 직접적인 삭제를 지양한다면, 로컬 머신에서 rm -rf 대신 휴지통 명령(trash command)으로 대체하세요. 핵심은 정리를 지루하고 반복 가능하게 만드는 것입니다.

비밀 정보 유출 방지

스크래치 파일을 무시(ignore)하는 것만으로는 충분하지 않습니다. 무시된 파일이라도 로컬 도구에 의해 읽히거나, 프롬프트(prompt)에 복사되거나, 확장 프로그램에 의해 업로드되거나, 이슈(issue)에 붙여넣어질 수 있습니다.

가드레일(guardrails)을 추가하세요.

최소한 다음 사항을 준수해야 합니다:

• 스크래치패드에 .env 파일을 절대 저장하지 말 것
• 실제 고객 기록을 절대 덤프(dump)하지 말 것
• API 응답을 저장하기 전에 토큰(token)을 마스킹(mask)할 것
• 브라우저 세션 내보내기(browser session exports)를 저장소(repo)에 포함하지 말 것
• 스크래치 파일을 승격하기 전에 비밀 정보 스캔(secret scans)을 실행할 것

간단한 로컬 체크로 명백한 실수를 잡아낼 수 있습니다:

rg -n "(api_key|secret|token|password|BEGIN PRIVATE KEY)" temp/ || true

더 강력한 보호를 위해, pre-commit 및 CI에서 비밀 정보 스캐너(secret scanner)를 사용하세요. 스크래치패드 자체는 로컬에 있지만, 승격된 파일은 여전히 일반적인 보안 검사가 필요합니다.

노이즈 없이 증거 유지하기

에이전트 스크래치패드의 가장 좋은 용도 중 하나는 증거 수집(evidence collection)입니다. 에이전트에게 단순히 "테스트 통과"라고 말하라고 요청하는 대신, 작은 증거 아티팩트(proof artifacts)를 저장하도록 요청하세요.

예를 들어:

temp/review-notes/fix-summary.md
temp/traces/test-run.txt
temp/screenshots/settings-page-after.png

리뷰 노트는 다음과 같이 짧게 작성될 수 있습니다:

# 리뷰 노트 (Review Notes)

작업: 결제 동기화 타임아웃에 대한 재시도 동작 수정.
...

이렇게 하면 최종 커밋(commit)을 오염시키지 않으면서도 리뷰어에게 맥락(context)을 제공할 수 있습니다.

평가(Evals) 및 에이전트 하네스(Agent Harnesses)와 함께 스크래치패드 사용하기

AI 에이전트가 단순한 코드 완성(code completion)에서 더 긴 워크플로(workflows)로 발전함에 따라, 검증(verification)이 어려운 부분이 되고 있습니다. 에이전트는 그럴듯한 수정 사항을 빠르게 생성할 수 있지만, 그 수정 사항이 인간의 의도와 일치함을 증명하는 것은 더 느린 작업입니다.

스크래치패드는 검증 아티팩트(verification artifacts)를 작업물 근처에 유지함으로써 도움을 줍니다:

• 수정 전 실패한 입력값 (failing inputs)
• 수정 후 통과한 출력값 (passing outputs)
• 모델 비교 노트 (model comparison notes)
• 트레이스 요약 (trace summaries)
• 에이전트가 고려한 엣지 케이스 (edge cases)
• 에이전트가 건너뛴 케이스

AI 제품 빌더들에게 이는 모델 동작을 테스트할 때 특히 유용합니다. 영구적인 평가 스위트(evaluation suite)에 포함할지 결정하기 전에, 임시 평가 출력물을 temp/traces/에 저장할 수 있습니다.

예시:

temp/traces/rag-answer-regression-raw.json
temp/traces/agent-tool-call-sample.json
temp/review-notes/eval-findings.md

그 다음, 안정적인 케이스만 승격(promote)시킵니다:

evals/fixtures/billing-policy-denial.json
evals/rubrics/source-grounding.yml

이렇게 하면 에이전트에게 탐색할 수 있는 여유를 주면서도 평가 시스템을 깨끗하게 유지할 수 있습니다.

1인 빌더를 위한 실질적인 워크플로

혼자서 개발하고 있다면 무거운 프로세스가 필요하지 않을 수도 있습니다. 하지만 경계(boundaries)는 여전히 필요합니다.

다음과 같은 가벼운 워크플로를 사용해 보세요:

1. 모든 에이전트 작업 시작 시, 실험을 위해 temp/를 사용하라고 지시합니다.
2. temp/ 외부의 프로덕션 변경 사항은 깨끗하고 최소한으로 유지하도록 요청합니다.
3. 작업이 완료되면 temp/review-notes/에 짧은 요약을 작성하도록 요청합니다.
4. 테스트를 실행하고 git diff를 검사합니다.
5. 유용한 스크래치 파일만 승격시킵니다.
6. 머지(merge) 후에는 스크래치패드를 정리합니다.

좋은 프롬프트(prompt)는 다음과 같습니다:

`temp/` 디렉토리를 스크래치 스크립트(scratch scripts), 덤프(dumps), 메모용으로 사용하세요. 레포지토리 루트(repo root)에 임시 파일을 생성하지 마세요. 최종 디프(diff)가 핵심에 집중되도록 유지하세요. 작업을 마치기 전에 실행된 테스트, 변경된 파일, 그리고 삭제하거나 승격(promote)시켜야 할 스크래치 파일 목록을 포함한 짧은 리뷰 노트를 작성하세요.

이 방식은 레포지토리의 청결함(hygiene)을 유지하면서도 에이전트의 속도를 놓치고 싶지 않은 개인 개발자, 마이크로 제품 팀, 그리고 기술 창업자(technical founders)에게 매우 효과적입니다.

팀을 위한 실질적인 워크플로우 (Practical Workflow)

팀 단위에서는 동일한 패턴에 더 엄격한 인수인계(handoff) 규칙이 추가로 필요합니다. 스크래치패드 경로를 문서화하고, 스크래치 파일을 승격시키기 전에 리뷰를 거치도록 하며, 승격된 아티팩트(artifacts)에서 비밀 정보(secrets)를 스캔하고, 장기 실행 브랜치(long-running branches)를 머지(merge)하기 전에 작업 폴더를 정리해야 합니다. 협업 작업의 경우, 서로 다른 에이전트의 흔적이 섞이지 않도록 temp/tasks/billing-retry/와 같이 작업별 전용 폴더를 사용하세요.

흔한 실수들 (Common Mistakes)

실수 1: 공유 .gitignore에 temp/를 추가하는 것

유혹적인 방법이지만, 다른 기여자들에게 유용한 관례를 숨길 수 있습니다. 개인적인 스크래치 작업을 위해서는 로컬 제외(Local excludes) 방식이 더 안전합니다. 만약 팀 전체가 진정으로 스크래치패드를 표준화한다면, 이를 명확하게 문서화하세요.

실수 2: 프로덕션 코드(production code)가 스크래치 파일에 의존하게 두는 것

만약 임포트(import) 경로가 temp/를 가리키고 있다면, 무언가 잘못된 것입니다. 스크래치패드 파일은 일회용입니다.

실수 3: 가공되지 않은 고객 데이터를 저장하는 것

에이전트들은 종종 예시를 요구합니다. 이때 합성 데이터(synthetic data)를 제공하세요. 반드시 실제 데이터를 검토해야 한다면, 레포지토리 외부에 보관하고 데이터 처리 규칙을 준수하세요.

실수 4: 리뷰 없이 정리하는 것

때때로 스크래치패드에는 유용한 증거가 포함되어 있을 수 있습니다. 특히 복잡한 디버깅(debugging)이나 모델 평가(model evaluation) 작업 이후에는 삭제하기 전에 반드시 리뷰하세요.

실수 5: 스크래치패드를 테스트의 대체제로 취급하는 것

트레이스(trace)는 테스트가 아닙니다. 디버그 스크립트(debug script)는 회귀 테스트 스위트(regression suite)가 아닙니다. 스크래치 아티팩트는 무엇을 영구적으로 남길지 결정하기 위한 발견 도구로 사용하세요.

구현 체크리스트 (Implementation Checklist)

오늘 바로 이 패턴을 도입하려면 다음 체크리스트를 사용하세요:

• 명확한 하위 폴더를 포함하는 temp/ 디렉토리 생성
• .git/info/exclude에 temp/ 추가
• 규칙이 담긴 temp/README.md 추가
• 스크래치패드 (scratchpad)를 사용하도록 에이전트 지침 (instructions) 업데이트
• 정리 (cleanup) 스크립트 추가
• 정식 반영 (promotion) 전 비밀 정보 스캔 (secret-scan) 알림 추가
• 복잡한 작업의 경우 에이전트에게 리뷰 노트 작성을 요청
• 안정적인 테스트, 문서, 피스처 (fixtures), 스크립트만 정식 반영

이것은 화려한 인프라가 아닙니다. 작은 워크플로 경계 (workflow boundary)입니다. 바로 그 점 때문에 효과가 있는 것입니다.

최종 요약 (Final Takeaway)

AI 코딩 에이전트는 탐색할 수 있는 공간이 있을 때 더 잘 작동합니다. 저장소 (repositories)는 추적되는 모든 파일이 존재해야 할 이유가 있을 때 더 잘 작동합니다.

AI 에이전트 스크래치패드 (scratchpad)는 이 두 가지를 모두 제공합니다. 실험 내용을 가시적으로 유지하고, 임시 파일이 Git을 오염시키는 것을 방지하며, 리뷰 증거를 위한 공간을 만들고, 정리를 스트레스가 아닌 일상적인 루틴으로 만들어 줍니다.