文档和
- 作者仓库星标 0
- 作者仓库 skills-registry
- 领域
- 文档
- 作者声明的智能体
- 未找到明确声明;不据此推断已兼容或已测试
- 静态检查
- 88 / 100 · 启发式扫描,不代表运行安全
- 运行环境证据
- 未执行;当前没有隔离运行测试证据
- 作者 / 版本 / 许可证
- @tomevault-io · 未声明许可证
- 上下文用量评级
- 低消耗
- 接入复杂程度
- 即装即用
- 是否需要外部接口密钥
- 不需要
- 兼容的系统
- macOS · Linux · Windows
- 运行环境要求
- 未检出明确要求
- 检测到的文件与系统行为
-
- 只读
- 允许写入 / 修改
- 读取环境变量
- 网络行为
- 仅限本地
- 安装命令数
- 无(仅作为资料)
需要注意: 未声明工具权限范围;实际权限由运行环境决定。
# 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 -->
章节与文件索引
按说明文件中的顺序排列。
概述
何时使用
配套脚本:scripts/create-adr.sh
架构决策记录 (ADR)
何时撰写 ADR
文件/命令 -> scripts/create-adr.sh · docs/decisions/ · assets/adr-template.md · bash ./scripts/skill-toolset.sh resource documentation-and-adrs assets/adr-template.md · npm install · cp .env.example .env · npm run dev · npm test
内容校验值 -> 9a59737eacc8
当前原文的自动摘译,尚未人工审校。
概述
记录决策,而不仅仅是代码。最有价值的文档抓住了“原因”——导致决策的背景、限制和权衡。代码显示什么被构建;文档解释了为什么以这种方式构建以及考虑了哪些替代方案。这种上下文对于未来在代码库中工作的人类和代理至关重要。
何时使用
做出重要的架构决策 在竞争方法之间进行选择 添加或更改公共 API 发布改变面向用户的行为的功能 将新的团队成员(或代理)引入项目
配套脚本:scripts/create-adr.sh
从技能模板创建按顺序编号的 ADR:脚本自动编号、从标题派生文件名,并填写下面 ADR 模板中的日期和部分标题。
架构决策记录 (ADR)
ADR 捕捉了重大技术决策背后的推理。它们是您可以编写的最高价值的文档。
何时撰写 ADR
选择框架、库或主要依赖项 设计数据模型或数据库模式 选择身份验证策略 决定 API 架构(REST、GraphQL 或 tRPC) 在构建工具、托管平台或基础设施之间进行选择