Troubleshooting
Agent Keeps Creating Duplicate Files?
Stop the clone chaos with a simple filing protocol your agent can follow every time.
Community users keep reporting the same pattern: the agent cannot find the latest file, creates a new one, and now you have three versions with nearly the same name. This is fixable.
Root cause: most duplicate-file loops happen when naming rules are vague and there is no required "search before write" step.
What good file behavior looks like
- One canonical folder per project
- One canonical filename per deliverable type
- Search existing files before creating a new one
- Ask before creating "v2/final/final-final" variants
5-step fix (copy this workflow)
1) Pick a single home folder
Do not let outputs spread across random directories. Put project files in one stable path.
workspace/
projects/
newsletter/
drafts/
final/
assets/
2) Define deterministic file names
Use names based on date + slug + status. Avoid free-form titles.
2026-04-03-newsletter-draft.md
2026-04-03-newsletter-final.md
3) Require "find before create"
Add a hard rule in AGENTS.md: search for existing candidate files first, then update the newest matching file unless explicitly told to create new.
4) Add an explicit overwrite policy
Tell the agent what to do when a target file already exists: update in-place, create timestamp backup, or ask for confirmation.
5) Run a one-prompt smoke test
Ask the agent to update yesterday's draft. If it creates a duplicate, tighten rules before doing real work.
Paste-ready AGENTS.md block
## File management rules
- Before creating any file, search the target folder for existing matches.
- If a matching file exists, update it in place unless I explicitly request a new file.
- Use naming format: YYYY-MM-DD-topic-status.ext
- Never create "final-final" style names.
- If uncertain which file is canonical, ask one clarifying question before writing.
- After writing, report exact file path and why that file was selected.
Important: broad instructions like "organize everything" often cause agents to rename or duplicate aggressively. Give narrow, deterministic rules instead.
Quick cleanup plan for existing duplicates
- Sort files by modified time.
- Choose one canonical "latest" file.
- Move older variants into an
archive/ folder (don't delete yet).
- Add a short changelog note at top of the canonical file.
- Update AGENTS.md with the rules above.
Don't do bulk deletes first. Keep an archive until you confirm the canonical file really contains everything you need.
High-friction edge cases (and fixes)
- Everything saves to root: set one required project path in AGENTS.md and require the agent to print the selected path before writing.
- Two agents/sub-agents writing at once: use a single-writer rule (one manager writes final files, workers output notes only).
- Same filename across different folders: require absolute path + file size + modified time proof before edits.
- Cloud-sync conflict copies: if you see names like "(conflicted copy)", pause auto-org tasks and pick one canonical file first.
Known-good recovery prompt
Before writing anything:
1) Search for matching files in /projects/newsletter.
2) Return the top 3 candidates with absolute path + modified timestamp.
3) Ask me to confirm the canonical file.
4) After confirmation, edit only that file in place.
5) Return a short diff summary and exact saved path.
Do NOT create new files unless I explicitly say "create new".
When to escalate in #help
If duplicates continue after this workflow, share:
- Your AGENTS.md file rules section
- Two example duplicate filenames
- Your expected naming pattern
- The exact prompt that triggered duplicate creation
Bottom line: duplicates are a policy problem, not a talent problem. Once you enforce path + naming + find-before-create, the chaos drops fast.