---

A Claude Code skill that prevents data architecture mistakes before they become technical debt.

Stop yourself from creating duplicate data stores, unnecessary sync scripts, and format sprawl. This skill activates automatically when you're about to make a storage decision and guides you toward single-source-of-truth architecture.

---

The Origin Story

This skill exists because I made the mistake it prevents.

I started a project with JSONL files for event tracking. Simple, append-only, good enough. Then I added SQLite for better querying. But I never migrated the existing consumers. The dashboard still read JSONL. Analytics still parsed flat files.

So I wrote sync scripts. "Temporary bridges." The result: 15MB of duplicate data, sync scripts running on every write, three consumers reading three copies of the same data, and nobody knew which source was canonical.

It took days to untangle. This skill makes sure you never have to.

How It Works

flowchart TD
    Q["You ask Claude Code<br/>a storage question"] --> G{"data-arch-guard<br/>activates"}
    G --> DT["Decision Tree<br/><i>JSONL · SQLite · JSON</i>"]
    G --> CL["Prevention Checklist<br/><i>6 questions</i>"]
    G --> RF["Red Flag Detector<br/><i>debt patterns</i>"]
    G --> SC["Duplicate Scanner<br/><i>scan-duplicates.sh</i>"]
    DT --> OUT["Single Source of Truth"]
    CL --> OUT
    RF --> OUT
    SC --> OUT

    style Q fill:#0d1117,stroke:#00ff88,color:#c9d1d9
    style G fill:#0d1117,stroke:#00d9ff,color:#c9d1d9
    style DT fill:#0d1117,stroke:#bb9af7,color:#c9d1d9
    style CL fill:#0d1117,stroke:#bb9af7,color:#c9d1d9
    style RF fill:#0d1117,stroke:#f7768e,color:#c9d1d9
    style SC fill:#0d1117,stroke:#e0af68,color:#c9d1d9
    style OUT fill:#0d1117,stroke:#00ff88,color:#c9d1d9

Loading

When you ask Claude Code about data storage — "should I use JSONL or SQLite?", "should I sync this data?", "which format for events?" — data-arch-guard activates and provides:

Decision Tree JSONL vs SQLite vs JSON Clear YES/NO criteria for every storage choice structured unbounded queryable	Prevention Checklist 6 questions before any new store Answer these before you add a single file ssot consumers canonical
Red Flags Debt patterns, caught early Signals you're about to create technical debt sync-scripts bridges sprawl	Duplicate Scanner scan-duplicates.sh Audits any project for data duplication bash zero-deps portable

Installation

Option 1: Clone directly (recommended)

git clone https://github.com/Dicoangelo/data-arch-guard.git ~/.claude/skills/data-arch-guard
chmod +x ~/.claude/skills/data-arch-guard/scripts/scan-duplicates.sh

Restart Claude Code — the skill loads automatically.

Option 2: Manual install

# Create the skills directory if it doesn't exist
mkdir -p ~/.claude/skills

# Copy the skill
cp -r data-arch-guard ~/.claude/skills/data-arch-guard

# Make the scanner executable
chmod +x ~/.claude/skills/data-arch-guard/scripts/scan-duplicates.sh

Usage

The skill activates automatically when you ask Claude Code questions like:

• "Should I create a JSONL file for tracking events?"
• "Should I use SQLite or JSONL?"
• "I need to sync data between two stores"
• "Which storage format should I use?"

You can also invoke it directly with /data-arch-guard.

Duplicate Scanner

Run the included script to audit any project for data architecture issues:

# Scan current directory
bash ~/.claude/skills/data-arch-guard/scripts/scan-duplicates.sh .

# Scan a specific project
bash ~/.claude/skills/data-arch-guard/scripts/scan-duplicates.sh /path/to/project

The scanner finds:

• Same data stored in multiple formats (JSONL + SQLite)
• Sync/bridge scripts that indicate duplication
• Oversized JSONL files that should be in a database
• JSON files that have grown beyond config size

What's Inside

data-arch-guard/
├── SKILL.md                          # Core skill (triggers, decision tree, checklists)
├── references/
│   ├── examples.md                   # Real-world good and bad patterns
│   ├── principles.md                 # 5 architecture principles (SSOT, Database First, etc.)
│   └── format-guide.md               # When to use SQLite vs JSONL vs JSON vs Redis vs Postgres
└── scripts/
    └── scan-duplicates.sh            # Finds potential data duplication in any project

The Core Decision

Need to store data?
│
├─ Structured with schema?    → Database
├─ Will it grow unbounded?    → Database
├─ Need to query/filter?      → Database
├─ Multiple consumers?        → Database
│
├─ Append-only log?           → JSONL is fine
├─ One-time export?           → JSONL is fine
└─ Simple config?             → JSON is fine

Need to sync data?
│
└─ WHY? → Fix root cause instead

Design Principles

1. Single Source of Truth — every piece of data has exactly one canonical home.
2. Database First — if it's structured, unbounded, or queried, it belongs in a database.
3. No sync without a reason — a sync script is almost always a symptom, not a solution.
4. Zero dependencies — pure Bash scanner, no install footprint.
5. Prevention over cleanup — catch the decision at the moment it's made, not days later.

License

MIT — see LICENSE.

---

_{Part of the Antigravity ecosystem by Metaventions AI — sovereign tooling for Claude Code.}