{"slug": "ai-agent-scratchpad-keep-coding-agents-fast-without-polluting-git", "title": "AI Agent Scratchpad: Keep Coding Agents Fast Without Polluting Git", "summary": "A developer proposes a pattern for managing temporary files created by AI coding agents without polluting the Git repository. The approach uses a dedicated scratchpad directory, such as `temp/`, with subfolders for scripts, dumps, drafts, traces, fixtures, screenshots, and review notes, and leverages `.git/info/exclude` for local-only ignoring. This keeps the repo clean while allowing agents to work freely.", "body_md": "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.\n\nThe risky part is not the mess itself. The risky part is when that mess becomes invisible. A noisy `git status`\n\ntrains you to ignore changes, while a hidden `.gitignore`\n\nrule 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.\n\nThis guide shows how to design an AI agent scratchpad for real development work.\n\nRecent 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.\n\nAn agent may create:\n\nNone 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.\n\nThe core problem is simple:\n\nAgents need room to think, test, and collect evidence. Production repos need clean boundaries.\n\nA scratchpad gives both sides what they need.\n\nMost teams start with the default pattern: let the agent write wherever it wants, then clean up before commit.\n\nThat works for tiny tasks. It breaks down when agents handle larger workflows.\n\nImagine a coding agent debugging a failing billing sync. It creates:\n\n```\nscripts/test_sync.py\nresponse.json\nnotes.md\ndebug.log\nbilling_dump.csv\nnew_test.py\nold_handler_backup.ts\n```\n\nA 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.\n\nNow review quality drops because the reviewer has to ask basic questions:\n\nA messy repo does not just waste time. It weakens trust in the AI workflow.\n\nA good agent scratchpad has three properties:\n\nThe important detail is local ignore. Instead of adding a shared `.gitignore`\n\nrule, use `.git/info/exclude`\n\n.\n\n`.git/info/exclude`\n\nbehaves like `.gitignore`\n\n, but it only applies to your local clone. It does not affect teammates, CI, or the shared repository.\n\nThat makes it ideal for agent scratch work.\n\nUse one top-level directory, such as `temp/`\n\n, `scratch/`\n\n, or `.agent-scratch/`\n\n. I prefer `temp/`\n\nbecause it is obvious and short.\n\nA practical layout looks like this:\n\n```\ntemp/\n  README.md\n  scripts/\n  dumps/\n  drafts/\n  traces/\n  fixtures/\n  screenshots/\n  review-notes/\n```\n\nEach subfolder has a job:\n\n| Folder | Use it for |\n|---|---|\n`scripts/` |\none-off debugging and migration helpers |\n`dumps/` |\nJSON, CSV, logs, API responses, benchmark outputs |\n`drafts/` |\nrough specs, prompt notes, article drafts, implementation plans |\n`traces/` |\nagent traces, tool-call summaries, evaluation output |\n`fixtures/` |\ntemporary test data that is not ready for committed tests |\n`screenshots/` |\nUI evidence and browser captures |\n`review-notes/` |\nhuman-readable summaries of what changed and why |\n\nThe 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.\n\nYou do not need a special tool. You can create the pattern with plain Git and a few shell commands.\n\n```\nmkdir -p temp/{scripts,dumps,drafts,traces,fixtures,screenshots,review-notes}\ncat > temp/README.md <<'EOF'\n# Local AI Scratchpad\n\nThis folder is for temporary agent and developer work.\n\nUse it for:\n- one-off scripts\n- logs and API dumps\n- draft notes\n- trace evidence\n- temporary fixtures\n- screenshots\n\nRules:\n- Do not store secrets here.\n- Do not depend on files here from production code.\n- Promote useful files into the repo intentionally.\n- Clean this folder before major merges.\nEOF\nprintf \"\\n# Local AI/developer scratchpad\\ntemp/\\n\" >> .git/info/exclude\n```\n\nNow `temp/`\n\nstays visible in your editor but does not appear in `git status`\n\n.\n\nCheck it:\n\n```\ngit status --short\n```\n\nIf the scratchpad does not show up, the local exclude is working.\n\nThe 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`\n\n, `CLAUDE.md`\n\n, `.cursorrules`\n\n, or another project instruction file.\n\nExample:\n\n```\n## AI Scratchpad\n\nUse `temp/` for temporary scripts, logs, API dumps, traces, and drafts.\nDo not create random temporary files in the project root.\nDo not store secrets, tokens, private customer data, or credentials in `temp/`.\nIf a scratchpad file becomes useful, explain why and ask before promoting it into tracked source.\nBefore finishing a task, summarize anything important left in `temp/review-notes/`.\n```\n\nThis small block prevents a surprising amount of clutter. It also gives reviewers a stable place to look for evidence.\n\nUse the scratchpad for work that helps solve the task but should not be committed by default.\n\nGood scratchpad candidates:\n\nBad scratchpad candidates:\n\n`.env`\n\nfilesA useful rule:\n\nIf the app needs it, it does not belong in the scratchpad. If the reviewer may need it, it might.\n\nSometimes 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.\n\nThat is fine. The promotion should be explicit.\n\nBefore moving a file out of `temp/`\n\n, ask four questions:\n\nExample promotion flow:\n\n```\n# From temporary reproduction script\nmv temp/scripts/repro-billing-sync.ts tests/regression/billing-sync-retry.test.ts\n\n# Then edit it into a real test before committing\ngit add tests/regression/billing-sync-retry.test.ts\n```\n\nDo not blindly move agent-created files into tracked folders. Treat scratchpad promotion like code review.\n\nA scratchpad that never gets cleaned becomes a junk drawer. Give developers and agents a safe cleanup command.\n\nCreate `scripts/clean-scratchpad.sh`\n\n:\n\n``` bash\n#!/usr/bin/env bash\nset -euo pipefail\n\nROOT=\"$(git rev-parse --show-toplevel)\"\nSCRATCH=\"$ROOT/temp\"\n\nif [ ! -d \"$SCRATCH\" ]; then\n  echo \"No temp/ scratchpad found.\"\n  exit 0\nfi\n\nfind \"$SCRATCH\" -mindepth 1 -maxdepth 1 \\\n  ! -name README.md \\\n  -exec rm -rf {} +\n\nmkdir -p \"$SCRATCH\"/{scripts,dumps,drafts,traces,fixtures,screenshots,review-notes}\n\necho \"Scratchpad cleaned.\"\n```\n\nIf your team avoids direct deletes, replace `rm -rf`\n\nwith a trash command on local machines. The point is to make cleanup boring and repeatable.\n\nIgnoring scratch files is not enough. Ignored files can still be read by local tools, copied into prompts, uploaded by extensions, or pasted into issues.\n\nAdd guardrails.\n\nAt minimum:\n\n`.env`\n\nfiles in the scratchpadA simple local check can catch obvious mistakes:\n\n```\nrg -n \"(api_key|secret|token|password|BEGIN PRIVATE KEY)\" temp/ || true\n```\n\nFor stronger protection, use a secret scanner in pre-commit and CI. The scratchpad itself is local, but promoted files still need normal security checks.\n\nOne 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.\n\nFor example:\n\n```\ntemp/review-notes/fix-summary.md\ntemp/traces/test-run.txt\ntemp/screenshots/settings-page-after.png\n```\n\nThe review note can be short:\n\n```\n# Review Notes\n\nTask: Fix retry behavior for billing sync timeout.\n\nChanged:\n- Added idempotency key reuse during retry.\n- Added regression test for timeout after provider accepted request.\n- Confirmed existing webhook dedupe still passes.\n\nEvidence:\n- `temp/traces/test-run.txt`\n- `temp/screenshots/billing-retry-log.png`\n\nNot promoted:\n- `temp/scripts/repro-billing-timeout.ts` was only used for local reproduction.\n```\n\nThis gives the reviewer context without polluting the final commit.\n\nAs 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.\n\nA scratchpad helps by keeping verification artifacts close to the work:\n\nFor AI product builders, this is especially useful when testing model behavior. You can store temporary eval output in `temp/traces/`\n\nbefore deciding whether it belongs in a permanent evaluation suite.\n\nExample:\n\n```\ntemp/traces/rag-answer-regression-raw.json\ntemp/traces/agent-tool-call-sample.json\ntemp/review-notes/eval-findings.md\n```\n\nThen promote only the stable cases:\n\n```\nevals/fixtures/billing-policy-denial.json\nevals/rubrics/source-grounding.yml\n```\n\nThis keeps your evaluation system clean while still giving agents room to explore.\n\nIf you are building alone, you may not need heavy process. You still need boundaries.\n\nUse this lightweight workflow:\n\n`temp/`\n\nfor experiments.`temp/`\n\nclean and minimal.`temp/review-notes/`\n\nwhen the task is done.`git diff`\n\n.A good prompt looks like this:\n\n```\nUse 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.\n```\n\nThis works well for solo developers, micro product teams, and technical founders who want agent speed without losing repo hygiene.\n\nTeams 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/`\n\nso evidence from different agents does not blend together.\n\n`temp/`\n\nin shared `.gitignore`\n\nThis 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.\n\nIf an import points into `temp/`\n\n, something went wrong. Scratchpad files are disposable.\n\nAgents 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.\n\nSometimes the scratchpad contains useful evidence. Review before deleting, especially after complex debugging or model evaluation work.\n\nA trace is not a test. A debug script is not a regression suite. Use scratch artifacts to discover what should become permanent.\n\nUse this checklist to add the pattern today:\n\n`temp/`\n\nwith clear subfolders.`temp/`\n\nto `.git/info/exclude`\n\n.`temp/README.md`\n\nwith rules.This is not fancy infrastructure. It is a small workflow boundary. That is why it works.\n\nAI coding agents work better when they have space to explore. Repositories work better when every tracked file has a reason to exist.\n\nAn 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.\n\nThe goal is not to make agents perfectly tidy. The goal is to make their mess safe, inspectable, and disposable.\n\nAn 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.\n\n`.gitignore`\n\nor `.git/info/exclude`\n\nfor scratch files?\nUse `.git/info/exclude`\n\nfor local scratch work. It ignores files only in your clone, so you avoid changing shared repository rules. Use `.gitignore`\n\nonly when the whole team agrees that a pattern should be ignored everywhere.\n\nUsually 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.\n\nOnly 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.\n\nPromote 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.\n\nNo. 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.", "url": "https://wpnews.pro/news/ai-agent-scratchpad-keep-coding-agents-fast-without-polluting-git", "canonical_source": "https://dev.to/jackm-singularity/ai-agent-scratchpad-keep-coding-agents-fast-without-polluting-git-329c", "published_at": "2026-06-28 02:54:55+00:00", "updated_at": "2026-06-28 03:33:36.704389+00:00", "lang": "en", "topics": ["developer-tools", "ai-agents", "large-language-models"], "entities": ["Git", "AI agent", "scratchpad", "temp/", ".git/info/exclude", "README.md"], "alternates": {"html": "https://wpnews.pro/news/ai-agent-scratchpad-keep-coding-agents-fast-without-polluting-git", "markdown": "https://wpnews.pro/news/ai-agent-scratchpad-keep-coding-agents-fast-without-polluting-git.md", "text": "https://wpnews.pro/news/ai-agent-scratchpad-keep-coding-agents-fast-without-polluting-git.txt", "jsonld": "https://wpnews.pro/news/ai-agent-scratchpad-keep-coding-agents-fast-without-polluting-git.jsonld"}}