文档和

文档 社区

技能解读

当前原文的自动摘译,尚未人工审校。

概述

记录决策,而不仅仅是代码。最有价值的文档抓住了“原因”——导致决策的背景、限制和权衡。代码显示什么被构建;文档解释了为什么以这种方式构建以及考虑了哪些替代方案。这种上下文对于未来在代码库中工作的人类和代理至关重要。

何时使用

做出重要的架构决策 在竞争方法之间进行选择 添加或更改公共 API 发布改变面向用户的行为的功能 将新的团队成员(或代理)引入项目

配套脚本:scripts/create-adr.sh

从技能模板创建按顺序编号的 ADR:脚本自动编号、从标题派生文件名,并填写下面 ADR 模板中的日期和部分标题。

架构决策记录 (ADR)

ADR 捕捉了重大技术决策背后的推理。它们是您可以编写的最高价值的文档。

何时撰写 ADR

选择框架、库或主要依赖项 设计数据模型或数据库模式 选择身份验证策略 决定 API 架构(REST、GraphQL 或 tRPC) 在构建工具、托管平台或基础设施之间进行选择

流狐档案 运行与权限由流狐静态检查推断,不代表作者声明或实际测试结果。
领域
文档
作者声明的智能体
未找到明确声明;不据此推断已兼容或已测试
静态检查
88 / 100 · 启发式扫描,不代表运行安全
运行环境证据
未执行;当前没有隔离运行测试证据
作者 / 版本 / 许可证
@tomevault-io · 未声明许可证
上下文用量评级
低消耗
接入复杂程度
即装即用
是否需要外部接口密钥
不需要
兼容的系统
macOS · Linux · Windows
运行环境要求
未检出明确要求
检测到的文件与系统行为
  • 只读
  • 允许写入 / 修改
  • 读取环境变量
网络行为
仅限本地
安装命令数
无(仅作为资料)

需要注意: 未声明工具权限范围;实际权限由运行环境决定。

作者说明文件(原文) SKILL.md
# Documentation and ADRs

## Overview

Document decisions, not just code. The most valuable documentation captures the *why* --- the context, constraints, and trade-offs that led to a decision. Code shows *what* was built; documentation explains *why it was built this way* and *what alternatives were considered*. This context is essential for future humans and agents working in the codebase.

## When to Use

- Making a significant architectural decision
- Choosing between competing approaches
- Adding or changing a public API
- Shipping a feature that changes user-facing behavior
- Onboarding new team members (or agents) to the project
- When you find yourself explaining the same thing repeatedly

**When NOT to use:** Don't document obvious code. Don't add comments that restate what the code already says. Don't write docs for throwaway prototypes.

## Companion Script: `scripts/create-adr.sh`

Creates a sequentially-numbered ADR from the skill's template:

```bash
# Basic: creates ADR-001-title.md in docs/decisions/
bash ./scripts/create-adr.sh "Use PostgreSQL for primary database"

# With status (default: Accepted)
bash ./scripts/create-adr.sh --status "Proposed" "API versioning strategy"

# Custom directory
bash ./scripts/create-adr.sh --dir docs/adrs "Title"
```

The script auto-numbers, derives the filename from the title, and
fills in the date and section headers from the ADR template below.

## Architecture Decision Records (ADRs)

ADRs capture the reasoning behind significant technical decisions. They're the highest-value documentation you can write.

### When to Write an ADR

- Choosing a framework, library, or major dependency
- Designing a data model or database schema
- Selecting an authentication strategy
- Deciding on an API architecture (REST vs. GraphQL vs. tRPC)
- Choosing between build tools, hosting platforms, or infrastructure
- Any decision that would be expensive to reverse

### Lightweight ADR Format (Preferred for Most Decisions)

Most decisions don't need a full template. If a decision is hard to reverse, surprising without context, and the result of a real trade-off, record it as a single paragraph:

```markdown
# ADR-014: Use PostgreSQL for write model, read models in Redis

The write model needs ACID transactions (order state changes must be atomic).
PostgreSQL gives us that with a well-understood operational story. Read models
are projected into Redis for sub-millisecond query performance on the dashboard.
We considered keeping everything in Postgres, but dashboard queries would need
complex aggregates that are hard to optimize. Redis lets us pre-compute the
shapes the dashboard needs. Trade-off: eventual consistency between write and
read models (~500ms lag), which is acceptable per ADR-007.
```

**That's it.** The value is in recording *that* a decision was made and *why* --- not in filling out sections.

Only expand to the full format when:
- The decision had multiple serious alternatives worth remembering
- The consequences are non-obvious and need explicit documentation
- The decision supersedes a previous ADR

### When to Offer an ADR

All three of these must be true:

1. **Hard to reverse** --- the cost of changing your mind later is meaningful
2. **Surprising without context** --- a future reader will look at the code and wonder "why did they do it this way?"
3. **The result of a real trade-off** --- there were genuine alternatives and you picked one for specific reasons

If any is missing, skip the ADR.

### ADR Template (Full Format)

For decisions that need the full treatment, store ADRs in `docs/decisions/` with sequential numbering:

> See `assets/adr-template.md` (L3) for the complete template with status, date, context,
> decision, alternatives, and consequences sections. Load with:
> `bash ./scripts/skill-toolset.sh resource documentation-and-adrs assets/adr-template.md`

### ADR Lifecycle

```
PROPOSED -> ACCEPTED -> (SUPERSEDED or DEPRECATED)
```

- **Don't delete old ADRs.** They capture historical context.
- When a decision changes, write a new ADR that references and supersedes the old one.

## Inline Documentation

### When to Comment

Comment the *why*, not the *what*:

```typescript
// BAD: Restates the code
// Increment counter by 1
counter += 1;

// GOOD: Explains non-obvious intent
// Rate limit uses a sliding window --- reset counter at window boundary,
// not on a fixed schedule, to prevent burst attacks at window edges
if (now - windowStart > WINDOW_SIZE_MS) {
  counter = 0;
  windowStart = now;
}
```

### When NOT to Comment

```typescript
// Don't comment self-explanatory code
function calculateTotal(items: CartItem[]): number {
  return items.reduce((sum, item) => sum + item.price * item.quantity, 0);
}

// Don't leave TODO comments for things you should just do now
// TODO: add error handling  <- Just add it

// Don't leave commented-out code
// const oldImplementation = () => { ... }  <- Delete it, git has history
```

### Document Known Gotchas

```typescript
/**
 * IMPORTANT: This function must be called before the first render.
 * If called after hydration, it causes a flash of unstyled content
 * because the theme context isn't available during SSR.
 *
 * See ADR-003 for the full design rationale.
 */
export function initializeTheme(theme: Theme): void {
  // ...
}
```

## API Documentation

For public APIs (REST, GraphQL, library interfaces):

### Inline with Types (Preferred for TypeScript)

```typescript
/**
 * Creates a new task.
 *
 * @param input - Task creation data (title required, description optional)
 * @returns The created task with server-generated ID and timestamps
 * @throws {ValidationError} If title is empty or exceeds 200 characters
 * @throws {AuthenticationError} If the user is not authenticated
 *
 * @example
 * const task = await createTask({ title: 'Buy groceries' });
 * console.log(task.id); // "task_abc123"
 */
export async function createTask(input: CreateTaskInput): Promise<Task> {
  // ...
}
```

### OpenAPI / Swagger for REST APIs

```yaml
paths:
  /api/tasks:
    post:
      summary: Create a task
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateTaskInput'
      responses:
        '201':
          description: Task created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Task'
        '422':
          description: Validation error
```

## README Structure

Every project should have a README that covers:

```markdown
# Project Name

One-paragraph description of what this project does.

## Quick Start
1. Clone the repo
2. Install dependencies: `npm install`
3. Set up environment: `cp .env.example .env`
4. Run the dev server: `npm run dev`

## Commands
| Command | Description |
|---------|-------------|
| `npm run dev` | Start development server |
| `npm test` | Run tests |
| `npm run build` | Production build |
| `npm run lint` | Run linter |

## Architecture
Brief overview of the project structure and key design decisions.
Link to ADRs for details.

## Contributing
How to contribute, coding standards, PR process.
```

## Changelog Maintenance

For shipped features:

```markdown
# Changelog

## [1.2.0] - 2025-01-20
### Added
- Task sharing: users can share tasks with team members (#123)
- Email notifications for task assignments (#124)

### Fixed
- Duplicate tasks appearing when rapidly clicking create button (#125)

### Changed
- Task list now loads 50 items per page (was 20) for better UX (#126)
```

## Documentation for Agents

Special consideration for AI agent context:

- **CLAUDE.md / rules files** --- Document project conventions so agents follow them
- **Spec files** --- Keep specs updated so agents build the right thing
- **ADRs** --- Help agents understand why past decisions were made (prevents re-deciding)
- **Inline gotchas** --- Prevent agents from falling into known traps

## Common Rationalizations

| Rationalization | Reality |
|---|---|
| "The code is self-documenting" | Code shows what. It doesn't show why, what alternatives were rejected, or what constraints apply. |
| "We'll write docs when the API stabilizes" | APIs stabilize faster when you document them. The doc is the first test of the design. |
| "Nobody reads docs" | Agents do. Future engineers do. Your 3-months-later self does. |
| "ADRs are overhead" | A 10-minute ADR prevents a 2-hour debate about the same decision six months later. |
| "Comments get outdated" | Comments on *why* are stable. Comments on *what* get outdated --- that's why you only write the former. |

## Red Flags

- Architectural decisions with no written rationale
- Public APIs with no documentation or types
- README that doesn't explain how to run the project
- Commented-out code instead of deletion
- TODO comments that have been there for weeks
- No ADRs in a project with significant architectural choices
- Documentation that restates the code instead of explaining intent

## Verification

After documenting:

- [ ] ADRs exist for all significant architectural decisions
- [ ] README covers quick start, commands, and architecture overview
- [ ] API functions have parameter and return type documentation
- [ ] Known gotchas are documented inline where they matter
- [ ] No commented-out code remains
- [ ] Rules files (CLAUDE.md etc.) are current and accurate

---
> Source: [B67687/agentic-workflows](https://github.com/B67687/agentic-workflows) — distributed by [TomeVault](https://tomevault.io).
<!-- tomevault:4.0:skill_md:2026-05-22 -->

讨论

基于 GitHub Discussions。登录 GitHub 即可参与讨论、点赞、订阅更新。