ai-decisions

name

ai-decisions

description

Captures architectural and development decisions made during AI-assisted coding sessions and persists them to all AI agent context files (CLAUDE.md, .kiro/steering/, .cursor/rules/, .github/copilot-instructions.md). Use this skill whenever the user says "I decided to use", "let's use X", "the pattern is", "remember that", "update the project files", "record this decision", introduces a new library/framework/component, or wants to record/sync a decision. Also triggers proactively when Claude detects a technology choice, architectural pattern, UI component selection, recurring task rule, or build convention being established mid-conversation — in those cases, ask the user if they want to record it.

AI Decisions

Maintains a canonical source of truth in .ai/decisions/ and syncs it to all AI agent context files detected in the project.

Source of Truth Structure

.ai/
  decisions/
    patterns.md         <- architectural and design patterns
    tech-stack.md       <- libraries, frameworks, tools chosen
    ui-components.md    <- UI component libraries and specific components adopted
    conventions.md      <- code style, naming, file structure rules
    recurring-tasks.md  <- tasks that must happen together (e.g. update i18n files)
    build.md            <- build steps, verification, CI requirements

Managed Agent Files

File	Tool	Format
CLAUDE.md	Claude Code	Single markdown with sections
.kiro/steering/decisions-{category}.md	Kiro	Per-category files with YAML frontmatter
.cursor/rules/decisions-{category}.mdc	Cursor	Per-category files with YAML frontmatter
.github/copilot-instructions.md	GitHub Copilot	Single merged markdown

---

Workflow

Step 1: Understand the Decision

Extract from the conversation:

• What was decided (library, pattern, component, task rule, convention)
• Why (brief rationale if mentioned)
• Category (see category reference below)

If the decision is ambiguous, ask for clarification. If you detected it proactively, ask: "I noticed you're using [X] — do you want me to record this decision in the project files?"

Step 2: Initialize if Needed

Check if .ai/decisions/ exists. If not, create the directory and all 6 category files using the templates at the bottom of this file.

Then detect which agent files exist in the project:

ls CLAUDE.md 2>/dev/null
ls .kiro/steering/ 2>/dev/null
ls .cursor/rules/ 2>/dev/null
ls .github/copilot-instructions.md 2>/dev/null

Only update agent files that already exist. Do not create agent files the user has not initialized. Exception: if no agent file exists at all, create CLAUDE.md as the default.

Step 3: Update the Source of Truth

Append the decision to the correct .ai/decisions/*.md file using this format:

### [Decision Title] — YYYY-MM-DD
**Decision**: [What was decided]
**Rationale**: [Why, if known]

If the decision supersedes a previous one (e.g. switching from library A to B), mark the old entry as superseded:

~~### Old Decision — date~~ *(superseded by [New Decision])*

Step 4: Sync Agent Files

After updating the source of truth, regenerate all detected agent files by reading the full updated content of .ai/decisions/.

CLAUDE.md

# AI Decisions

> Auto-generated from `.ai/decisions/`. Do not edit manually.
> Last updated: YYYY-MM-DD

## How to use this context

Before starting any task in this project, read the canonical decision files to get the latest context:

- `.ai/decisions/patterns.md`
- `.ai/decisions/tech-stack.md`
- `.ai/decisions/ui-components.md`
- `.ai/decisions/conventions.md`
- `.ai/decisions/recurring-tasks.md`
- `.ai/decisions/build.md`

The content is also synced inline below as a quick reference snapshot.

## Patterns
{content from patterns.md}

## Tech Stack
{content from tech-stack.md}

## UI Components
{content from ui-components.md}

## Conventions
{content from conventions.md}

## Recurring Tasks
{content from recurring-tasks.md}

## Build
{content from build.md}

Kiro — .kiro/steering/decisions-{category}.md

One file per category that has content:

---
inclusion: always
description: {Category} decisions for this project
---

# {Category}

> Source: `.ai/decisions/{category}.md` — read that file for the latest version.

{content from category file}

Cursor — .cursor/rules/decisions-{category}.mdc

---
description: {Category} decisions for this project
alwaysApply: true
---

# {Category}

> Source: `.ai/decisions/{category}.md` — read that file for the latest version.

{content from category file}

GitHub Copilot — .github/copilot-instructions.md

Merge all categories into one file:

# Project AI Instructions

> Auto-generated from `.ai/decisions/`. Read the files in `.ai/decisions/` for the latest canonical version.

## Patterns
...
## Tech Stack
...
{etc.}

Step 5: Confirm

Show the user:

1. What was recorded and in which category
2. Which agent files were updated
3. The exact text added to the source of truth

---

Category Reference

Category	File	Examples
Patterns	patterns.md	Repository pattern, CQRS, functional components only
Tech Stack	tech-stack.md	Next.js, Drizzle ORM, Effect-TS, Stripe
UI Components	ui-components.md	shadcn/ui Button, custom DatePicker, Radix dialogs
Conventions	conventions.md	File naming, import order, no default exports
Recurring Tasks	recurring-tasks.md	Update i18n files, run migrations, update changelog
Build	build.md	Always type-check before commit, verify Vercel preview

---

Proactive Detection

Suggest recording a decision when the user:

• Imports a package not seen before in the project
• Uses phrases like "let's use", "I chose", "the pattern is", "remember to", "every time", "always when"
• Installs a new dependency (npm install, bun add, pip install, etc.)
• Establishes a rule that applies to future work ("always", "every time", "whenever")

Ask naturally: "Do you want me to record this decision in the project files?" Do not ask for every line of code — only when a genuine project-level decision emerges.

---

Initial Templates

When initializing .ai/decisions/ for the first time, create these files:

patterns.md

# Architectural Patterns

Architectural and design patterns adopted in this project.

tech-stack.md

# Tech Stack

Libraries, frameworks, and tools chosen for this project.

ui-components.md

# UI Components

UI libraries and specific components adopted in this project.

conventions.md

# Conventions

Code style, naming conventions, and file structure rules.

recurring-tasks.md

# Recurring Tasks

Tasks that must always be performed together with specific actions.

build.md

# Build & Verification

Build steps, CI requirements, and verification rules.