Initial repository structure and approach¶
- Date: 2026-03-06
- Status: Accepted
- Tags:
structuretooling
Context¶
Managing a growing set of AI tools (Claude Code, Cursor, Windsurf, Gemini) had become ad hoc — skills, rules, and prompts were scattered across local configs, notes, and memory. There was no single source of truth for what was configured, why it was configured that way, or how approaches evolved over time.
The goal was a structured, version-controlled knowledgebase that could grow with the tooling landscape without becoming unwieldy.
Decision¶
Create a hybrid repository structure: top-level directories per tool, with artifact-type subdirectories nested within each. Architectural decisions are tracked as ADRs in a shared decisions/ folder. A central README.md serves as the index and map.
Tools included at baseline: Claude Code, Cursor, Windsurf, Gemini Pro.
Alternatives Considered¶
| Option | Why Rejected |
|---|---|
Artifact-type at top level (rules/, skills/, etc.) |
Makes it harder to reason about a single tool holistically; tool-specific context gets fragmented |
| Separate repo per tool | Too much overhead; cross-tool patterns and decisions have no natural home |
| Flat structure (all files in root) | Doesn't scale past a handful of files |
| Wiki (Notion, Confluence, etc.) | Not version-controlled; harder to co-edit with AI tools; no git history |
Consequences¶
Positive:
- Each tool's full configuration surface is visible in one place
- ADRs create a durable record of why things are set up the way they are
- Git history provides a timeline of how the approach evolves
- Easy to hand off or onboard collaborators
Negative / Trade-offs:
- Requires discipline to keep in sync with actual tool configs (the repo is a reference, not the live config source for most tools)
- ADR overhead for small decisions may feel like friction initially
Ongoing obligations:
- When a tool's configuration changes significantly, update the relevant directory
- When a structural decision is made, log an ADR before or shortly after
- Keep README index table current as tools are added or removed
ADRs are immutable. If this decision changes, create a new ADR with status "Superseded by" pointing here, and update this record's status.