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.

Why Agent Scratchpads Matter Now

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:

• one-off reproduction scripts
• API response dumps
• benchmark outputs
• migration drafts
• screenshots or UI notes
• local test fixtures
• prompt experiments
• failed implementation attempts
• summaries of files it read

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.

The Bad Pattern: Random Temporary Files Everywhere

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:

• Is this file part of the feature?
• Was this generated by the agent?
• Can I delete it?
• Does it contain secrets or private data?
• Did the agent accidentally change shared ignore rules?
• Why is the diff so noisy?

A messy repo does not just waste time. It weakens trust in the AI workflow.

The Better Pattern: A Local, Visible, Ignored Scratchpad

A good agent scratchpad has three properties:

1. Visible to humans and AI tools so files can be referenced, inspected, and reused.
2. Ignored by Git locally so temporary files do not clutter commits.
3. Structured by purpose so cleanup and review are predictable.

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.

Recommended Folder Structure

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:

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.

Set Up the Scratchpad Manually

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.

Add Agent Instructions

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.

What Should Go Into the Scratchpad?

Use the scratchpad for work that helps solve the task but should not be committed by default.

Good scratchpad candidates:

• a script that reproduces a bug once
• a curl response from a local API
• a model output comparison
• a quick benchmark result
• a temporary SQLite database
• a browser screenshot for a UI check
• notes from inspecting a third-party SDK
• a failed approach the reviewer may want to understand

Bad scratchpad candidates:

• production code
• real migration files
• committed test fixtures
• secrets
• .env files
• user exports
• private customer data
• files that CI must read
• anything the app imports at runtime

A useful rule:

If the app needs it, it does not belong in the scratchpad. If the reviewer may need it, it might.

Promote Files Intentionally

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:

1. Does this file support the product, tests, docs, or operations long term?
2. Is it free of secrets and private data?
3. Is the name clear enough for future maintainers?
4. Did we remove throwaway assumptions from the agent’s experiment?

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.

Add a Cleanup Command

A scratchpad that never gets cleaned becomes a junk drawer. Give developers and agents a safe cleanup command.

Create scripts/clean-scratchpad.sh:

#!/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.

Protect Against Secret Leaks

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:

• never store .env files in the scratchpad
• never dump real customer records
• mask tokens before saving API responses
• keep browser session exports out of the repo
• run secret scans before promoting any scratch file

A 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.

Keep Evidence Without Keeping Noise

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.

Use Scratchpads With Evals and Agent Harnesses

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:

• failing inputs before the fix
• passing outputs after the fix
• model comparison notes
• trace summaries
• edge cases the agent considered
• cases the agent skipped

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.

A Practical Workflow for Solo Builders

If you are building alone, you may not need heavy process. You still need boundaries.

Use this lightweight workflow:

1. Start every agent task by telling it to use temp/ for experiments.
2. Ask it to keep production changes outside temp/ clean and minimal.
3. Ask for a short summary in temp/review-notes/ when the task is done.
4. Run tests and inspect git diff.
5. Promote only useful scratch files.
6. Clean the scratchpad after merge.

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.

A Practical Workflow for Teams

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.

Common Mistakes

Mistake 1: Putting 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.

Mistake 2: Letting production code depend on scratch files

If an import points into temp/, something went wrong. Scratchpad files are disposable.

Mistake 3: Saving raw customer data

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.

Mistake 4: Cleaning without review

Sometimes the scratchpad contains useful evidence. Review before deleting, especially after complex debugging or model evaluation work.

Mistake 5: Treating the scratchpad as a replacement for tests

A trace is not a test. A debug script is not a regression suite. Use scratch artifacts to discover what should become permanent.

Implementation Checklist

Use this checklist to add the pattern today:

• [ ] Create temp/ with clear subfolders.
• [ ] Add temp/ to .git/info/exclude.
• [ ] Add temp/README.md with rules.
• [ ] Update agent instructions to use the scratchpad.
• [ ] Add a cleanup script.
• [ ] Add secret-scan reminders before promotion.
• [ ] Ask agents to write review notes for complex tasks.
• [ ] Promote only stable tests, docs, fixtures, and scripts.

This is not fancy infrastructure. It is a small workflow boundary. That is why it works.

Final Takeaway

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.

FAQ

What is an AI agent scratchpad?

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.

Should I use .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.

Can coding agents read files in an ignored scratchpad?

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.

Is it safe to store API responses in a scratchpad?

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.

When should a scratchpad file become a real repo file?

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.

Does this replace agent observability or eval tooling?

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.