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.

Load 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.

Load 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.”

Load 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