I keep an /artifacts folder in every repo now
It holds the email threads, query plans, and screenshots that Claude Code needs and the codebase doesn't have.
In the web UI you drag files into the chat or the project. In the CLI there's no “chat window”, so the files live in the repo.
The folder holds raw material: exported logs, vendor PDFs converted to markdown, screenshots of broken UI, API response dumps, meeting notes I pasted out of Slack. Anything I would have dragged into a chat window.
Sharing is what makes this worth doing. When I write a spec and feed the agent an email thread as context, that thread shaped the spec. My colleague reruns the session next week and starts from nothing. The repo fixes that.
A structure that survives more than two weeks:
artifacts/
README.md # one line per file: where it came from, why
<ticket-id>/ # scoped to the task
local/ # gitignored, never leaves my machine
local/ carries the weight. Email exports contain names and addresses. Log dumps contain tokens. If everything goes to git by default, someone leaks something in month two and your security team kills the whole practice. Default to local/, promote to shared when the content is clean.
I also added a line to CLAUDE.md telling the agent to check artifacts/README.md before asking me for context, and a Makefile target that runs markitdown over any PDF that lands in the folder. PDFs make poor agent input.
Artifacts die when the ticket merges. Anything worth keeping goes to /docs, rewritten for humans.
This is a folder and a naming convention. It moves agent context out of my terminal history and into something my team can read.
Do you keep agent context in the repo, or does it live in your shell history?
278 views