# 条目示例

展示包含全部字段的规范条目示例。

## Learning：纠正

```markdown
## [LRN-20250115-001] correction

**Logged**: 2025-01-15T10:30:00Z
**Priority**: high
**Status**: pending
**Area**: tests

### Summary
错误地认为 pytest fixture 默认都是 function 级作用域

### Details
在编写测试 fixture 时，我误以为所有 fixture 默认都是 function 作用域。
用户纠正说，虽然 function scope 确实是 pytest 默认值，但这个代码库的约定是：
数据库连接这类昂贵资源使用 module 级 fixture，以提升测试性能。

### Suggested Action
当创建涉及昂贵初始化成本的 fixture（数据库、网络等）时，
不要默认使用 function scope，应先检查现有 fixture 的作用域约定。

### Metadata
- Source: user_feedback
- Related Files: tests/conftest.py
- Tags: pytest, testing, fixtures

---
```

## Learning：知识缺口（已解决）

```markdown
## [LRN-20250115-002] knowledge_gap

**Logged**: 2025-01-15T14:22:00Z
**Priority**: medium
**Status**: resolved
**Area**: config

### Summary
项目使用 pnpm，而不是 npm，作为包管理器

### Details
我尝试执行 `npm install`，但项目实际上使用 pnpm workspaces。
锁文件是 `pnpm-lock.yaml`，而不是 `package-lock.json`。

### Suggested Action
在默认使用 npm 之前，先检查是否存在 `pnpm-lock.yaml` 或 `pnpm-workspace.yaml`。
如果存在，应使用 `pnpm install`。

### Metadata
- Source: error
- Related Files: pnpm-lock.yaml, pnpm-workspace.yaml
- Tags: package-manager, pnpm, setup

### Resolution
- **Resolved**: 2025-01-15T14:30:00Z
- **Commit/PR**: N/A - 知识更新
- **Notes**: 已加入 CLAUDE.md，供后续参考

---
```

## Learning：已提升到 CLAUDE.md

```markdown
## [LRN-20250115-003] best_practice

**Logged**: 2025-01-15T16:00:00Z
**Priority**: high
**Status**: promoted
**Promoted**: CLAUDE.md
**Area**: backend

### Summary
API 响应必须回传请求头中的 correlation ID

### Details
所有 API 响应都应回传请求中的 `X-Correlation-ID` 头。
这是分布式链路追踪所必需的。缺少该头会导致可观测性链路中断。

### Suggested Action
在 API handler 中始终包含 correlation ID 透传逻辑。

### Metadata
- Source: user_feedback
- Related Files: src/middleware/correlation.ts
- Tags: api, observability, tracing

---
```

## Learning：已提升到 AGENTS.md

```markdown
## [LRN-20250116-001] best_practice

**Logged**: 2025-01-16T09:00:00Z
**Priority**: high
**Status**: promoted
**Promoted**: AGENTS.md
**Area**: backend

### Summary
OpenAPI 变更后必须重新生成 API client

### Details
修改 API endpoint 后，必须重新生成 TypeScript client。
忘记执行会导致运行时才暴露出的类型不匹配问题。
生成脚本本身也会顺带做校验。

### Suggested Action
将以下规则加入 agent 工作流：任何 API 变更后，执行 `pnpm run generate:api`。

### Metadata
- Source: error
- Related Files: openapi.yaml, src/client/api.ts
- Tags: api, codegen, typescript

---
```

## Error 条目

```markdown
## [ERR-20250115-A3F] docker_build

**Logged**: 2025-01-15T09:15:00Z
**Priority**: high
**Status**: pending
**Area**: infra

### Summary
Docker build 在 M1 Mac 上因平台不匹配而失败

### Error
```
error: failed to solve: python:3.11-slim: no match for platform linux/arm64
```

### Context
- Command: `docker build -t myapp .`
- Dockerfile 使用 `FROM python:3.11-slim`
- 运行环境是 Apple Silicon（M1/M2）

### Suggested Fix
增加平台参数：`docker build --platform linux/amd64 -t myapp .`
或者更新 Dockerfile：`FROM --platform=linux/amd64 python:3.11-slim`

### Metadata
- Reproducible: yes
- Related Files: Dockerfile

---
```

## Error 条目：重复问题

```markdown
## [ERR-20250120-B2C] api_timeout

**Logged**: 2025-01-20T11:30:00Z
**Priority**: critical
**Status**: pending
**Area**: backend

### Summary
结账流程中第三方支付 API 超时

### Error
```
TimeoutError: Request to payments.example.com timed out after 30000ms
```

### Context
- Command: POST /api/checkout
- 超时设置为 30s
- 在高峰时段发生（午间、晚间）

### Suggested Fix
实现带指数退避的重试机制，并考虑加入熔断模式。

### Metadata
- Reproducible: yes（高峰时段）
- Related Files: src/services/payment.ts
- See Also: ERR-20250115-X1Y, ERR-20250118-Z3W

---
```

## 功能请求

```markdown
## [FEAT-20250115-001] export_to_csv

**Logged**: 2025-01-15T16:45:00Z
**Priority**: medium
**Status**: pending
**Area**: backend

### Requested Capability
将分析结果导出为 CSV 格式

### User Context
用户每周都会生成报告，并需要把结果分享给非技术同事在 Excel 中查看。
当前只能手工复制输出内容。

### Complexity Estimate
simple

### Suggested Implementation
为 analyze 命令增加 `--output csv` 选项，并使用标准 csv 模块。
可以沿用现有 `--output json` 的设计模式。

### Metadata
- Frequency: recurring
- Related Features: analyze command, json output

---
```

## 功能请求：已解决

```markdown
## [FEAT-20250110-002] dark_mode

**Logged**: 2025-01-10T14:00:00Z
**Priority**: low
**Status**: resolved
**Area**: frontend

### Requested Capability
为 dashboard 提供暗色模式

### User Context
用户经常深夜使用，觉得当前亮色界面比较刺眼。
另外也有其他用户非正式提到过类似需求。

### Complexity Estimate
medium

### Suggested Implementation
使用 CSS 变量管理颜色，并在用户设置里增加开关。
同时考虑系统主题偏好自动识别。

### Metadata
- Frequency: recurring
- Related Features: user settings, theme system

### Resolution
- **Resolved**: 2025-01-18T16:00:00Z
- **Commit/PR**: #142
- **Notes**: 已实现系统主题检测与手动切换

---
```

## Learning：已提升为技能

```markdown
## [LRN-20250118-001] best_practice

**Logged**: 2025-01-18T11:00:00Z
**Priority**: high
**Status**: promoted_to_skill
**Skill-Path**: skills/docker-m1-fixes
**Area**: infra

### Summary
Docker build 在 Apple Silicon 上因平台不匹配而失败

### Details
在 M1 / M2 Mac 上构建 Docker 镜像时，构建会失败，
因为基础镜像没有 ARM64 变体。这是一个常见问题，
会影响很多开发者。

### Suggested Action
在 docker build 命令上加 `--platform linux/amd64`，
或者在 Dockerfile 中使用 `FROM --platform=linux/amd64`。

### Metadata
- Source: error
- Related Files: Dockerfile
- Tags: docker, arm64, m1, apple-silicon
- See Also: ERR-20250115-A3F, ERR-20250117-B2D

---
```

## 提炼后的技能示例

当上面的 learning 被提炼为 skill 后，会变成：

**文件**：`skills/docker-m1-fixes/SKILL.md`

```markdown
---
name: docker-m1-fixes
description: "修复 Apple Silicon（M1/M2）上的 Docker build 平台不匹配问题。适用于 docker build 因平台错误而失败时。"
---

# Docker M1 Fixes

解决 Apple Silicon Mac 上常见的 Docker build 问题。

## Quick Reference

| Error | Fix |
|-------|-----|
| `no match for platform linux/arm64` | 在 build 时加 `--platform linux/amd64` |
| 镜像能启动但运行崩溃 | 使用仿真层或改用支持 ARM 的基础镜像 |

## 问题描述
```