维护变更日志

其他 社区

技能解读

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

何时激活

修改文件的每个会话结束。在结束之前或当用户发出完成信号时,将一个条目附加到存储库根目录中的CHANGELOG.md。在以下情况下也激活: 用户明确要求更新变更日志 开始新会话 - 首先阅读变更日志以了解最近的历史记录

变更日志位置

存储库根目录中的CHANGELOG.md。如果不存在则创建它。

规则

保持简洁。每个条目应可在 10 秒内浏览完毕。没有段落。关注“什么”和“为什么”,而不是“如何”。不要描述实现细节——差异讲述了这个故事。变更日志讲述了人类的故事。按逻辑更改分组,而不是按文件分组。即使涉及 3 个文件,“添加共享 Postgres 实例”也是一项。

开始新会话

开始工作时,请阅读CHANGELOG.md以了解: 最近做了什么 上一个会话留下了哪些“后续步骤” 项目的当前状态 这提供了跨会话的连续性,而无需单独依赖内存文件。

注释

变更日志补充(而不是取代)git 历史记录。 Git 显示更改了什么代码;变更日志显示做出了什么决定以及原因。如果存储库还没有 CHANGELOG.md,请创建一个带有标头的 CHANGELOG.md:不要单独提交更改日志 - 将其包含在与其记录的更改相同的提交中。

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

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

作者说明文件(原文) SKILL.md

# Maintain Changelog

## When to Activate

**End of every session that modified files.** Before wrapping up or when the user signals
they're done, append an entry to `CHANGELOG.md` in the repo root.

Also activate when:
- The user explicitly asks to update the changelog
- Starting a new session — read the changelog first to understand recent history

## Changelog Location

`CHANGELOG.md` in the repository root. Create it if it doesn't exist.

## Entry Format

```markdown
## YYYY-MM-DD — <brief title>

### What changed
- Bullet points describing each meaningful change
- Group related changes together
- Include file paths for significant additions/modifications

### Why
- One or two sentences explaining the motivation or context

### Files touched
- `path/to/new-file.yaml` (new)
- `path/to/modified-file.yaml` (modified)
- `path/to/deleted-file.yaml` (deleted)
```

## Rules

1. **Be concise.** Each entry should be scannable in 10 seconds. No paragraphs.
2. **Focus on "what" and "why", not "how".** Don't describe implementation details —
   the diff tells that story. The changelog tells the *human* story.
3. **Group by logical change, not by file.** "Added shared Postgres instance" is one
   entry even if it touched 3 files.
4. **Newest entries at the top.** Reverse chronological order.
5. **Don't log trivial changes.** Typo fixes, formatting, or changelog-only updates
   don't need entries.
6. **Include context that won't be obvious later.** Item IDs, IP addresses, design
   decisions — things that help future sessions understand the state of the world.
7. **Don't duplicate commit messages.** The changelog is higher-level than git log.
   One changelog entry may span multiple commits.

## Example

```markdown
# Changelog

## 2026-02-09 — Add shared PostgreSQL instance

### What changed
- Created CNPG Cluster `home-1` in `postgres` namespace (single instance, 10Gi on zfs-nfs)
- Added managed roles for `kutt` and `linkding` with ESO-managed passwords (auto-rotation via CNPG)
- Created 4 Vaultwarden login items for postgres credentials (superuser, app, kutt, linkding)
- Added ArgoCD Application for postgres

### Why
Shared Postgres instance for apps migrating off SQLite. Per-app user isolation with
automated password rotation through the ESO → CNPG pipeline.

### Files touched
- `apps/postgres/postgres.yaml` (new)
- `apps/external-secrets/externalsecrets.yaml` (modified — 4 new ExternalSecrets)
- `apps/argocd/apps.yaml` (modified — postgres Application added)

### Next steps
- Create `kutt_db` and `linkding_db` databases manually after cluster is healthy
- Rotate change-me passwords in Vaultwarden
- Migrate Kutt from SQLite to Postgres
```

## Starting a New Session

When beginning work, read `CHANGELOG.md` to understand:
- What was done recently
- What "next steps" were left by the previous session
- The current state of the project

This provides continuity across sessions without relying on memory files alone.

## Notes

- The changelog complements (not replaces) git history. Git shows *what code changed*;
  the changelog shows *what decisions were made and why*.
- If the repo doesn't have a CHANGELOG.md yet, create one with a header:
  ```markdown
  # Changelog
  ```
- Don't commit the changelog separately — include it in the same commit as the changes
  it documents.

讨论

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