Skip to content

Initial repository structure and approach

  • Date: 2026-03-06
  • Status: Accepted
  • Tags: structure tooling

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.