Code Patterns
Best practices distilled from implementation lessons. These patterns prevent common bugs in file I/O, data persistence, and validation.
Core Principle
LEARN FROM MISTAKES - DON'T REPEAT THEM
Each pattern here was extracted from a real bug or issue. Apply these patterns proactively to prevent the same mistakes.
When to Use
Always use for: File-based state, shared resources, data persistence, validation layers, concurrent access
Especially when: Multiple processes/hooks access same file, persisting JSON data, creating factory functions, implementing save/load logic
The Patterns
1. File Locking (references/file-io.md)
Advisory file locking for shared state access.
Problem: Multiple processes writing to same file causes data corruption or race conditions.
Solution: Use .lock file pattern with timeout and stale lock detection.
⚠️ MUST READ when: Implementing file-based state accessed by multiple hooks/processes
2. Atomic Writes (references/data-persistence.md)
Safe file persistence that survives crashes.
Problem: writeFileSync() mid-write crash corrupts file.
Solution: Write to .tmp, rename to final path (atomic on POSIX), handle Windows with backup pattern.
⚠️ MUST READ when: Persisting any JSON/data file that must survive unexpected termination
3. Schema Validation (references/data-validation.md)
Validate before every persist operation.
Problem: Factory functions create invalid data that persists and causes downstream issues.
Solution: Validate at creation AND before every write. Never trust "it was validated earlier."
⚠️ MUST READ when: Creating factory functions, implementing create/update operations, building data pipelines
Quick Reference
Shared file access → file-io.md (add locking)
JSON persistence → data-persistence.md (atomic writes)
Factory function → data-validation.md (validate output)
Prevention Checklist
Before implementing file I/O:
- [ ] Will multiple processes access this file?
- [ ] What happens if write crashes mid-operation?
- [ ] Is data validated before every write?
- [ ] Are stale locks handled (dead process detection)?
Origin
These patterns were extracted from ACE (Agentic Context Engineering) implementation review:
- Race condition in concurrent delta writes → file-io.md
- File corruption risk on crash → data-persistence.md
- Invalid deltas persisting → data-validation.md
IMPORTANT Task Planning Notes
- Always plan and break many small todo tasks
- Always add a final review todo task to review the works done at the end to find any fix or enhancement needed