dotfiles/agents/AGENTS.md

Personal preferences

Workflow

• Specs, plans, and design docs go into the repo they describe. When brainstorming, plan-mode, or any flow produces a persistent document (design spec, implementation plan, ADR, etc.), the final destination is always the working tree of the project it belongs to — typically under docs/ (or wherever the project conventionally keeps them). Scratch locations like ~/.claude/plans/<slug>.md are fine during plan mode, but the moment plan mode exits with an approved artifact, copy it into the repo and git commit it. Don't ship a feature while its spec or plan still lives only in a scratch file. If a project's AGENTS.md / CLAUDE.md specifies a different directory, that wins.

Sandbox

• Always run commands sandboxed first. Only use dangerouslyDisableSandbox: true as a last resort after a sandbox-related failure — never preemptively.
• On sandbox failure: analyze the error message for the blocked path, then suggest adding it to sandbox.filesystem.allowWrite in ~/.claude/settings.json. Only fall back to dangerouslyDisableSandbox: true if the path can't be determined or the user prefers it.

Temporary Files

• Use $TMPDIR or .tmp/ (project-local) for temporary files. Never use /tmp directly or paths like /Library/Application Support — those are not in the sandbox allowlist and trigger permission prompts.
• $TMPDIR is set by the sandbox to a writable path. .tmp/ inside the project directory is always writable without prompts.
• Ensure .tmp/ is listed in .gitignore when creating temp files in a tracked repo.

Tooling

• ccc for semantic code search. Repos containing a .cocoindex_code/ directory are indexed by ccc. Reach for it on conceptual questions ("where is X used / which files do Y / what handles Z"), where a keyword grep would miss indirect usage: ccc search '<concept>' --path '**'. Pass --path '**' — without it, results are filtered to the current working directory's subtree. The ccc skill has the full reference; grep/rg/find remain fine for exact-string lookups.