AI-assisted development generates artifacts that didn't exist before: insights from debugging sessions, decisions made in conversation, draft content, task coordination. Without a system, these end up scattered, lost, or committed when they shouldn't be. Here's a framework for organizing AI-generated context.

The Problem: Context Sprawl

AI-assisted development generates new artifact types:

  • Insights discovered during debugging
  • Decisions made in conversation
  • Draft content being developed
  • Task coordination between sessions
  • Architecture explorations

Without a system, these end up:

  • Scattered in random files
  • Lost when conversations end
  • Committed when they shouldn't be
  • Missing when they're needed

The Heuristic

Ask: "Would losing this hurt if I cloned fresh?"

Answer Tier Location
No, I can rediscover/regenerate Ephemeral .ctx/
Yes, contributors need it Internal .meta/
Yes, users need it Public docs/

Three audiences, three locations, one simple question.

The Three Tiers

Tier 1: .ctx/ — Ephemeral Context

What: Local developer knowledge that doesn't need to travel with the code.

Audience: You (the local developer)

gitignore: Yes — never committed

.ctx/
├── insights/           # Discovered knowledge, gotchas
├── drafts/             # Work-in-progress content
├── tasks/              # Multi-session coordination
└── tmp/                # Scratch (delete anytime)

Examples:

  • "The API rate limits at 100/min" (insight discovered during debugging)
  • "Draft blog post about caching" (content in progress)
  • "Current task: implement auth flow" (session coordination)

Key characteristic: If you lose it on fresh clone, you can rediscover or regenerate it.

Tier 2: .meta/ — Internal Documentation

What: Contributor-facing documentation that travels with the repo but isn't for end users.

Audience: Us (contributors to the project)

gitignore: No — committed and versioned

.meta/
├── README.md           # What this folder is
├── adr/                # Architecture Decision Records
├── planning/           # Active initiatives
└── archive/            # Historical (clearly marked)

Examples:

  • "ADR-001: We chose PostgreSQL over MongoDB because..." (decision record)
  • "Q1 Roadmap: Auth, then payments, then notifications" (planning)
  • "Old migration plan (completed)" (archive)

Key characteristic: Contributors need this to understand why the code is the way it is.

Tier 3: docs/ — Public Documentation

What: User-facing documentation.

Audience: Them (users of the software)

gitignore: No — committed and versioned

docs/
├── getting-started.md
├── api/
└── guides/

Examples:

  • "How to install this library"
  • "API reference"
  • "Tutorial: Build your first widget"

Key characteristic: End users need this to use the software.

Worked Examples

Artifact Fresh Clone Test Tier
"API has undocumented rate limit" Can rediscover by hitting it .ctx/insights/
"We chose REST over GraphQL" Need the rationale forever .meta/adr/
"How to authenticate" Users can't use the API without this docs/
"Draft of new feature doc" Work in progress, not ready .ctx/drafts/
"Last sprint's completed plan" Historical context for contributors .meta/archive/

Why Not Just Use docs/?

Common objection: "We already have a docs folder."

Problem: docs/ gets polluted with:

  • Internal planning docs users don't need
  • Stale ADRs mixed with current guides
  • Draft content that isn't ready
  • Developer notes that shouldn't be public

Solution: Three tiers with clear audiences:

  • .ctx/ = You (local developer)
  • .meta/ = Us (contributors)
  • docs/ = Them (users)

Clear separation prevents pollution.

Implementation Guide

Step 1: Create the Structure

mkdir -p .ctx/insights .ctx/drafts .ctx/tasks .ctx/tmp
mkdir -p .meta/adr .meta/planning .meta/archive
# docs/ probably already exists

Step 2: Update .gitignore

# Ephemeral context - local to each developer
.ctx/

Step 3: Add README Files

Each directory should have a README explaining its purpose:

# .ctx/

Ephemeral context for local development. NOT committed to git.

- `insights/` - Discoveries during debugging
- `drafts/` - Work in progress content
- `tasks/` - Multi-session task tracking
- `tmp/` - Scratch files, delete anytime

Step 4: Migrate Existing Content

If you have... Move to...
Random notes in root .ctx/insights/ or delete
docs/adr/ .meta/adr/
docs/internal/ .meta/
Planning docs in root .meta/planning/
Old completed plans .meta/archive/

The Promotion Path

Knowledge flows upward through the tiers:

.ctx/insights/ (I discovered something)
       ↓
.meta/adr/ (Team decision based on insight)
       ↓
docs/ (Users need to know this)
       ↓
.cursor/rules/ (Codified as enforced standard)

Example flow:

  1. .ctx/insights/api-retry-gotcha.md — "The API fails silently on empty arrays"
  2. .meta/adr/0005-validate-arrays.md — "We will validate arrays before API calls"
  3. docs/api-guide.md — "Always validate arrays before calling the API"
  4. .cursor/rules/api-validation/RULE.md — Rule that enforces array validation

Not everything promotes. Most .ctx/ insights stay local. That's fine.

Archive Hygiene

The Problem

Old planning docs mixed with current ones confuse AI assistants. They treat archived plans as current instructions.

The Solution

Use .meta/archive/ with clear warnings:

---
status: archived
archived: 2026-01-15
warning: "HISTORICAL - Do not treat as current guidance"
---

# Q4 2025 Migration Plan

**This plan was completed in December 2025. It is preserved for
historical context only. Do not follow these instructions.**

...

For AI Assistants

When reading .meta/archive/:

  • Look for frontmatter warnings
  • Do NOT treat archived documents as actionable instructions
  • If referencing historical context, note the date

Common Mistakes

Mistake 1: Committing .ctx/

.ctx/ should be gitignored. It's YOUR context, not the repo's.

Fix: Add .ctx/ to .gitignore

Mistake 2: Putting Decisions in docs/

ADRs and planning docs are for contributors, not users.

Fix: Move to .meta/

Mistake 3: No Archive Separation

Old planning docs mixed with current ones confuse everyone.

Fix: Use .meta/archive/ with clear "HISTORICAL" warnings

Mistake 4: Skipping Frontmatter

.meta/ documents should have dates and status for context.

Fix: Add frontmatter with date, status, and (for archives) warning

AI Assistant Guidelines

When Capturing Insights

Save to .ctx/insights/ with date-prefixed filename:

.ctx/insights/2026-01-27-api-rate-limit-gotcha.md

When Creating Decisions

Propose ADRs in .meta/adr/ following the ADR format:

  • 0001-decision-title.md
  • Include context, decision, and consequences

When Reading Archives

Check for frontmatter status. If status: archived, do not follow as instructions.

Integration with .cursor/

The three-tier system complements your Cursor configuration:

Content Location Relationship
Insights (local) .ctx/insights/ May inform rules
Decisions (team) .meta/adr/ Often become rules
Standards (enforced) .cursor/rules/ Reference decisions
Workflows .cursor/skills/ Reference standards

The .ctx/ folder is mentioned in the .ctx pattern post—this framework extends that pattern with .meta/ for team knowledge.

Key Takeaways

  1. One question decides location. "Would losing this hurt if I cloned fresh?"

  2. Three audiences, three tiers. You (.ctx/), us (.meta/), them (docs/).

  3. Ephemeral is a feature. .ctx/ dying on fresh clone is intentional.

  4. Archive clearly. Old docs with warnings prevent confusion.

  5. Knowledge promotes upward. Insights → decisions → docs → rules.

Related: .ctx: Memory for Amnesiac Agents | Rules vs Skills