ai-context-writer（AI 上下文编写器）

AI Context Writer Skill

Use this skill when creating or updating ai-context.md files that document modules in the codebase. These files are indexed by the context-crawler and surfaced via /modules, /module, and /module-search commands.

File Location

Context files must be named exactly ai-context.md and placed at the root of the module:

packages/my-package/ai-context.md    # Internal module
apps/my-app/ai-context.md            # Internal module
.context/external-lib/ai-context.md  # External reference (submodule)

Required Structure

Frontmatter (YAML)

---
path: packages/my-package
summary: One-line description mentioning purpose and key technologies
tags: [effect, http-client, sdk-wrapper]
---

Frontmatter Fields:

• path - Module identifier (relative path from repo root)
• summary - Single sentence, concise description for module listings
• tags - Optional categorization for search (technologies, domains)

Markdown Body Sections

# Module Name

High-level overview paragraph explaining the module's purpose.

## Architecture

┌──────────────────┐
│    Component     │
└──────────────────┘
        │
        ▼
┌──────────────────┐
│     Service      │
└──────────────────┘

Brief explanation of the architecture diagram.

## Core Modules

| Module | Purpose |
|--------|---------|
| `Service.ts` | Main service implementation |
| `Client.ts` | HTTP client wrapper |

## Usage Patterns

### Basic Usage

import * as MyModule from "@/packages/my-package" import { Effect } from "effect"

const program = Effect.gen(function* () { const service = yield* MyModule.Service return yield* service.doThing() })

## Key Patterns

### Pattern Name

Description of when and why to use this pattern.

// Example code

## Design Decisions

**AD-1: Decision Title**
Explanation of the decision and trade-offs.

**AD-2: Another Decision**
Why this approach was chosen over alternatives.

## Dependencies

- `effect` - Core Effect library
- `@effect/platform` - Platform abstractions

## Spec Reference

- [specs/my-feature/DESIGN.md](../specs/my-feature/DESIGN.md)

Section Guidelines

Architecture Diagram

Use simple ASCII box-and-arrow diagrams:

┌──────────────┐     ┌──────────────┐
│   Service    │────▶│    Client    │
└──────────────┘     └──────────────┘
        │
        ▼
┌──────────────┐
│   Repository │
└──────────────┘

Characters: ┌ ┐ └ ┘ │ ─ ▼ ▲ ◀ ▶ ────▶

Core Modules Table

Quick reference for key files:

| Module | Purpose |
|--------|---------|
| `ParallelClient.ts` | HTTP client with Effect integration |
| `ParallelRun.ts` | Async task execution |
| `Errors.ts` | Tagged error types |

Usage Patterns

Always include:

• Full imports with namespace pattern (import * as X)
• Effect.gen for effectful code
• Layer construction if services are involved

import * as MyService from "@/packages/my-service"
import { Effect, Layer } from "effect"

const program = Effect.gen(function* () {
  const svc = yield* MyService.Service
  return yield* svc.operation()
})

const live = program.pipe(
  Effect.provide(MyService.Live)
)

Design Decisions

Use AD-N format for traceability:

**AD-1: Use Effect.gen over flatMap chains**
Effect.gen provides cleaner syntax and better stack traces. The generator pattern
makes sequential operations readable without callback nesting.

**AD-2: Schema.TaggedStruct for all domain types**
Automatic discriminator and Data equality support. Enables pattern matching
with Match.typeTags.

Dependencies

List external packages the module depends on:

## Dependencies

- `effect` - Core Effect types and functions
- `@effect/platform` - FileSystem, HttpClient, Terminal
- `@effect/schema` - Runtime validation and serialization

Summary Writing

The summary is critical - it appears in /modules listings.

Good summaries:

• "Effect wrapper for Parallel AI SDK - web search, content extraction, and async task runs"
• "React frontend with Effect-Atom state management and TanStack Router"
• "SQLite-backed workflow engine for durable execution patterns"

Bad summaries:

• "A module for doing stuff" (too vague)
• "This is the main package that handles various functionality" (no specifics)

Summary formula: [Primary purpose] - [key feature 1], [key feature 2], and [key feature 3]

Discovery and Indexing

Context files are indexed by context-crawler.ts:

1. Recursively finds all ai-context.md files
2. Extracts frontmatter (path, summary, tags)
3. Falls back to first paragraph if no summary
4. Excludes node_modules, .git, dist, build, .turbo

Module Classification

• Internal: Local ai-context.md files in packages/apps
• External: Submodules from .gitmodules (may lack ai-context.md)

External modules without context files show: (grep for implementation details)

Commands for Discovery

# List all modules with summaries
/modules

# Get full content of specific module
/module packages/parallel

# Search modules by pattern
/module-search http

Complete Example

---
path: packages/parallel
summary: Effect wrapper for Parallel AI SDK - web search, content extraction, and async task runs
tags: [effect, sdk-wrapper, parallel-ai, http-client]
---

# Parallel SDK Effect Wrapper

Effect-native wrapper for the Parallel AI SDK. Injects Effect's HttpClient as the
fetch implementation, providing typed errors, deferred computation patterns, and
composable layer construction.

## Architecture

┌─────────────────────────────────────────────────────────────────┐
│                         User Code                                │
│                    (Effect programs)                             │
└─────────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────────┐
│                      ParallelClient                              │
│    ┌──────────────┐  ┌──────────────┐  ┌──────────────────┐    │
│    │   search()   │  │  extract()   │  │   createRun()    │    │
│    └──────────────┘  └──────────────┘  └──────────────────┘    │
└─────────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────────┐
│                    Effect HttpClient                             │
│              (injected via Layer.provide)                        │
└─────────────────────────────────────────────────────────────────┘

## Core Modules

| Module | Purpose |
|--------|---------|
| `ParallelClient.ts` | Service interface with Effect operations |
| `ParallelClientLive.ts` | Live implementation using HttpClient |
| `ParallelRun.ts` | Async run execution with polling |
| `Errors.ts` | Tagged error types for failure handling |

## Usage Patterns

### Basic Search

import * as Parallel from "@/packages/parallel" import { Effect } from "effect"

const program = Effect.gen(function* () { const client = yield* Parallel.ParallelClient const results = yield* client.search({ query: "Effect TypeScript" }) return results })

const runnable = program.pipe( Effect.provide(Parallel.Live) )

### Error Handling

import * as Parallel from "@/packages/parallel" import { Effect } from "effect"

const safe = program.pipe( Effect.catchTag("ParallelApiError", (e) => Effect.succeed({ error: e.message }) ), Effect.catchTag("ParallelNetworkError", () => Effect.succeed({ error: "Network unavailable" }) ) )

## Design Decisions

**AD-1: Inject HttpClient via Layer**
Enables testing with mock HTTP responses. Production uses FetchHttpClient,
tests use a custom client that returns canned responses.

**AD-2: Tagged errors for all failure modes**
ParallelApiError, ParallelNetworkError, ParallelTimeoutError. Enables
precise error handling with catchTag.

## Dependencies

- `effect` - Core runtime
- `@effect/platform` - HttpClient abstraction
- `parallel-sdk` - Underlying SDK (via .context/parallel-sdk-typescript)

## Spec Reference

- [specs/parallel/DESIGN.md](../../specs/parallel/DESIGN.md)

When to Use This Skill

• Adding a new package or app that should be discoverable
• Documenting an existing module for AI assistants
• Creating context for external libraries added as submodules
• Updating documentation after significant refactoring
• Ensuring modules appear in /modules listings

Key Principles

1. Frontmatter is required - path and summary enable indexing
2. Summary is critical - appears in all module listings
3. Architecture diagrams - visual overview aids understanding
4. Usage patterns with imports - show how to actually use the module
5. Design decisions - explain why, not just what
6. Code examples compile - include all necessary imports
7. Namespace imports - always import * as X from