Workflow
Stop File Chaos with BEST_PRACTICES.md
If your agent keeps creating duplicate files, forgetting your naming rules, or filing things in random folders, this one-file system fixes it fast.
Community pattern: users get good results for a few days, then file sprawl starts. Duplicate docs, unclear “final-final-v2” names, and random folder drift kill trust. You don’t need a giant AGENTS.md rewrite to fix this.
Reality check: your agent follows what is easiest to find in current context. If your file rules are scattered across chat history, they won’t be applied consistently.
The simple fix
- Create one reference file: BEST_PRACTICES.md.
- Put all file workflow rules there (naming, folder map, duplicate policy, archive policy).
- In AGENTS.md, add one short pointer to this file instead of duplicating rules.
- Before filing or project work, prompt: "Read BEST_PRACTICES.md first, then execute."
Starter template (copy/paste)
# BEST_PRACTICES.md
## 1) Canonical folder map
- drafts/ = active rough work
- deliverables/ = final outputs only
- archive/YYYY-MM/ = retired/old versions
## 2) Naming rules
- Use: YYYY-MM-DD-topic-short-slug.ext
- Never use: final-final, v2, new, copy
- Keep names lowercase and hyphenated
## 3) Find-before-create rule
Before creating any file:
1. Search for existing candidates by topic/slug.
2. If a likely file exists, update it instead of creating a new one.
3. If uncertain, ask one disambiguation question with exact candidate paths.
## 4) Duplicate prevention
- If duplicates exist, choose one canonical file.
- Move superseded files to archive/YYYY-MM/.
- Add a one-line note: "superseded by [path]"
## 5) Completion proof
For every write task, report:
- exact path written
- whether file was created vs updated
- 1-line summary of what changed
AGENTS.md pointer block
### File workflow contract
Before any organizing, writing, moving, or renaming:
1) Read BEST_PRACTICES.md
2) Follow it as the source of truth for file handling
3) If conflict appears, ask before proceeding
Avoid this trap: dumping 200 lines of file policy directly into AGENTS.md. It bloats routine context and still drifts over time.
2-minute repair flow when chaos already exists
- Pick one project folder and stop all parallel edits there.
- Ask the agent for a duplicate inventory list (filename + full path + last modified).
- Choose canonical files only; archive the rest.
- Create/update BEST_PRACTICES.md with the rules you actually want.
- Run one tiny canary task (single file update) and verify proof output.
Copy/paste control prompt
File task (strict):
1) Read BEST_PRACTICES.md first and summarize the rules you will follow.
2) Do a find-before-create scan for matching files.
3) Update existing canonical file when possible; do not create duplicates.
4) If ambiguity remains, ask one question with exact candidate paths.
5) After completion, return: exact path, created-or-updated, and one-line diff summary.
When to escalate to #help
- Agent keeps creating duplicates even after BEST_PRACTICES.md + canary task.
- Files appear in unexpected locations despite explicit workspace path constraints.
- Agent reports writes but no files exist at reported paths.
Bottom line: one clean reference file + find-before-create + proof output eliminates most file-organization loops.