# AI Agent Scratchpad: Keep Coding Agents Fast Without Polluting Git > Source: > Published: 2026-06-28 02:54:55+00:00 Coding agents are fast enough to create a mess before you notice it. One prompt can leave behind debug scripts, JSON dumps, half-finished notes, copied stack traces, and helper files that sit beside production code like they belong there. The risky part is not the mess itself. The risky part is when that mess becomes invisible. A noisy `git status` trains you to ignore changes, while a hidden `.gitignore` rule can make useful agent context disappear from your editor. If you build AI-assisted products, you need a better pattern: a visible scratchpad that agents can use freely, Git can ignore safely, and reviewers can clean without guessing. This guide shows how to design an AI agent scratchpad for real development work. Recent AI developer tooling is moving in the same direction: agents are getting longer-running, more tool-aware, and more deeply connected to repos, Slack, issue trackers, browsers, and local files. That is useful. It also means temporary work is no longer just a human habit. An agent may create: None of these belong in the main source tree forever. Some are valuable for review. Some are sensitive. Some are pure junk. Without a deliberate scratchpad, they all end up scattered across the project. The core problem is simple: Agents need room to think, test, and collect evidence. Production repos need clean boundaries. A scratchpad gives both sides what they need. Most teams start with the default pattern: let the agent write wherever it wants, then clean up before commit. That works for tiny tasks. It breaks down when agents handle larger workflows. Imagine a coding agent debugging a failing billing sync. It creates: ``` scripts/test_sync.py response.json notes.md debug.log billing_dump.csv new_test.py old_handler_backup.ts ``` A human comes back later and sees a wall of unrelated changes. Some files are real. Some are experiments. Some contain customer-like test data. Some are needed to understand the fix. Now review quality drops because the reviewer has to ask basic questions: A messy repo does not just waste time. It weakens trust in the AI workflow. A good agent scratchpad has three properties: The important detail is local ignore. Instead of adding a shared `.gitignore` rule, use `.git/info/exclude` . `.git/info/exclude` behaves like `.gitignore` , but it only applies to your local clone. It does not affect teammates, CI, or the shared repository. That makes it ideal for agent scratch work. Use one top-level directory, such as `temp/` , `scratch/` , or `.agent-scratch/` . I prefer `temp/` because it is obvious and short. A practical layout looks like this: ``` temp/ README.md scripts/ dumps/ drafts/ traces/ fixtures/ screenshots/ review-notes/ ``` Each subfolder has a job: | Folder | Use it for | |---|---| `scripts/` | one-off debugging and migration helpers | `dumps/` | JSON, CSV, logs, API responses, benchmark outputs | `drafts/` | rough specs, prompt notes, article drafts, implementation plans | `traces/` | agent traces, tool-call summaries, evaluation output | `fixtures/` | temporary test data that is not ready for committed tests | `screenshots/` | UI evidence and browser captures | `review-notes/` | human-readable summaries of what changed and why | The structure matters because agents follow visible conventions. If the scratchpad explains where to put things, the agent is less likely to scatter files across the repo. You do not need a special tool. You can create the pattern with plain Git and a few shell commands. ``` mkdir -p temp/{scripts,dumps,drafts,traces,fixtures,screenshots,review-notes} cat > temp/README.md <<'EOF' # Local AI Scratchpad This folder is for temporary agent and developer work. Use it for: - one-off scripts - logs and API dumps - draft notes - trace evidence - temporary fixtures - screenshots Rules: - Do not store secrets here. - Do not depend on files here from production code. - Promote useful files into the repo intentionally. - Clean this folder before major merges. EOF printf "\n# Local AI/developer scratchpad\ntemp/\n" >> .git/info/exclude ``` Now `temp/` stays visible in your editor but does not appear in `git status` . Check it: ``` git status --short ``` If the scratchpad does not show up, the local exclude is working. The scratchpad only works if agents know how to use it. Add a short instruction to your repo’s agent guidance file. Depending on your tools, that might be `AGENTS.md` , `CLAUDE.md` , `.cursorrules` , or another project instruction file. Example: ``` ## AI Scratchpad Use `temp/` for temporary scripts, logs, API dumps, traces, and drafts. Do not create random temporary files in the project root. Do not store secrets, tokens, private customer data, or credentials in `temp/`. If a scratchpad file becomes useful, explain why and ask before promoting it into tracked source. Before finishing a task, summarize anything important left in `temp/review-notes/`. ``` This small block prevents a surprising amount of clutter. It also gives reviewers a stable place to look for evidence. Use the scratchpad for work that helps solve the task but should not be committed by default. Good scratchpad candidates: Bad scratchpad candidates: `.env` filesA useful rule: If the app needs it, it does not belong in the scratchpad. If the reviewer may need it, it might. Sometimes a scratchpad file becomes real work. A debug script becomes a regression test. A draft schema becomes a migration. A temporary fixture becomes a stable test fixture. That is fine. The promotion should be explicit. Before moving a file out of `temp/` , ask four questions: Example promotion flow: ``` # From temporary reproduction script mv temp/scripts/repro-billing-sync.ts tests/regression/billing-sync-retry.test.ts # Then edit it into a real test before committing git add tests/regression/billing-sync-retry.test.ts ``` Do not blindly move agent-created files into tracked folders. Treat scratchpad promotion like code review. A scratchpad that never gets cleaned becomes a junk drawer. Give developers and agents a safe cleanup command. Create `scripts/clean-scratchpad.sh` : ``` bash #!/usr/bin/env bash set -euo pipefail ROOT="$(git rev-parse --show-toplevel)" SCRATCH="$ROOT/temp" if [ ! -d "$SCRATCH" ]; then echo "No temp/ scratchpad found." exit 0 fi find "$SCRATCH" -mindepth 1 -maxdepth 1 \ ! -name README.md \ -exec rm -rf {} + mkdir -p "$SCRATCH"/{scripts,dumps,drafts,traces,fixtures,screenshots,review-notes} echo "Scratchpad cleaned." ``` If your team avoids direct deletes, replace `rm -rf` with a trash command on local machines. The point is to make cleanup boring and repeatable. Ignoring scratch files is not enough. Ignored files can still be read by local tools, copied into prompts, uploaded by extensions, or pasted into issues. Add guardrails. At minimum: `.env` files in the scratchpadA simple local check can catch obvious mistakes: ``` rg -n "(api_key|secret|token|password|BEGIN PRIVATE KEY)" temp/ || true ``` For stronger protection, use a secret scanner in pre-commit and CI. The scratchpad itself is local, but promoted files still need normal security checks. One of the best uses of an agent scratchpad is evidence collection. Instead of asking the agent to merely say “tests pass,” ask it to save small proof artifacts. For example: ``` temp/review-notes/fix-summary.md temp/traces/test-run.txt temp/screenshots/settings-page-after.png ``` The review note can be short: ``` # Review Notes Task: Fix retry behavior for billing sync timeout. Changed: - Added idempotency key reuse during retry. - Added regression test for timeout after provider accepted request. - Confirmed existing webhook dedupe still passes. Evidence: - `temp/traces/test-run.txt` - `temp/screenshots/billing-retry-log.png` Not promoted: - `temp/scripts/repro-billing-timeout.ts` was only used for local reproduction. ``` This gives the reviewer context without polluting the final commit. As AI agents move from simple code completion to longer workflows, verification becomes the hard part. The agent can generate a plausible fix quickly. Proving the fix matches human intent is slower. A scratchpad helps by keeping verification artifacts close to the work: For AI product builders, this is especially useful when testing model behavior. You can store temporary eval output in `temp/traces/` before deciding whether it belongs in a permanent evaluation suite. Example: ``` temp/traces/rag-answer-regression-raw.json temp/traces/agent-tool-call-sample.json temp/review-notes/eval-findings.md ``` Then promote only the stable cases: ``` evals/fixtures/billing-policy-denial.json evals/rubrics/source-grounding.yml ``` This keeps your evaluation system clean while still giving agents room to explore. If you are building alone, you may not need heavy process. You still need boundaries. Use this lightweight workflow: `temp/` for experiments.`temp/` clean and minimal.`temp/review-notes/` when the task is done.`git diff` .A good prompt looks like this: ``` Use temp/ for scratch scripts, dumps, and notes. Do not create temporary files in the repo root. Keep the final diff focused. Before finishing, write a short review note listing tests run, files changed, and any scratch files that should be deleted or promoted. ``` This works well for solo developers, micro product teams, and technical founders who want agent speed without losing repo hygiene. Teams need the same pattern, plus stricter handoff rules: document the scratchpad path, require review before promoting scratch files, scan promoted artifacts for secrets, and clean task folders before merging long-running branches. For shared work, use task-specific folders like `temp/tasks/billing-retry/` so evidence from different agents does not blend together. `temp/` in shared `.gitignore` This is tempting, but it can hide useful conventions from other contributors. Local excludes are safer for personal scratch work. If the whole team truly standardizes on a scratchpad, document it clearly. If an import points into `temp/` , something went wrong. Scratchpad files are disposable. Agents often ask for examples. Give them synthetic data. If you must inspect real data, keep it outside the repo and follow your data handling rules. Sometimes the scratchpad contains useful evidence. Review before deleting, especially after complex debugging or model evaluation work. A trace is not a test. A debug script is not a regression suite. Use scratch artifacts to discover what should become permanent. Use this checklist to add the pattern today: `temp/` with clear subfolders.`temp/` to `.git/info/exclude` .`temp/README.md` with rules.This is not fancy infrastructure. It is a small workflow boundary. That is why it works. AI coding agents work better when they have space to explore. Repositories work better when every tracked file has a reason to exist. An AI agent scratchpad gives you both. It keeps experiments visible, prevents temporary files from polluting Git, creates a home for review evidence, and makes cleanup routine instead of stressful. The goal is not to make agents perfectly tidy. The goal is to make their mess safe, inspectable, and disposable. An AI agent scratchpad is a local folder where coding agents and developers can store temporary scripts, logs, drafts, traces, and test outputs without adding them to the committed source tree. `.gitignore` or `.git/info/exclude` for scratch files? Use `.git/info/exclude` for local scratch work. It ignores files only in your clone, so you avoid changing shared repository rules. Use `.gitignore` only when the whole team agrees that a pattern should be ignored everywhere. Usually yes. Git ignoring a file does not hide it from your editor or local AI tools. That is why a local scratchpad is useful: it stays visible for context but does not clutter commits. Only if they are sanitized. Do not store secrets, tokens, private user records, or customer exports. Mask sensitive fields before saving responses, and scan files before promoting anything into tracked code. Promote it when it has long-term value as a test, fixture, script, document, or operational artifact. Before promoting, rename it clearly, remove temporary assumptions, check for secrets, and review it like normal code. No. A scratchpad is a local workflow pattern. Observability and eval tooling are still needed for production agents. The scratchpad helps during development by keeping temporary evidence organized before it becomes permanent instrumentation or evaluation data.