关于 pythia-comment
pythia-comment 是一套用于编写 SQL 注释的规范，面向使用 pythia 修改 SQL 文件的开发者。它要求注释采用单行 ASCII 格式，记录日期、作者和变更内容，并将解释性文字引导至其他文档或测试。
主要功能
- 01单行日期、作者和变更格式
- 02仅覆盖 SQL 与 PL/SQL 注释
- 03要求 ASCII 字符
- 04将说明移至文档、测试或提交信息
适用场景
- 01为 SQL 修改添加简短注释
- 02避免数据库注释出现字符编码乱码
- 03将设计理由记录在规范或提交信息中
安装
复制下面的命令，在终端中运行。
npx skills add https:/安装后在 Claude Code 中输入/pythia-comment确认已加载。
详细介绍
注释——一行，或放在别处
开始时声明：“使用 pythia-comment——一行，日期 - 作者 - 改动内容。”
**阶段：**执行——编写期间适用，在 pythia apply 读取文件之前
注释是改动中唯一不会经过编译器检查、也不会被测试覆盖的部分，因此最容易腐烂。一行注释能经受下一次改写。段落则会变成一种断言，下一位读者必须先推翻它才能继续工作。
格式
-- 11/09/2026 - jdoe - source flag reads the mapping table, not the join
日期 - 作者 - 改动内容，日期格式为 DD/MM/YYYY。作者应填写开发者的账号，而不是 Agent 的：这不是 Agent 做出的决定；追责记录如果指向某个工具，就会成为死胡同。
PL/SQL 和 SQL 使用 --。这就是本技能涵盖的全部范围——即 pythia 会应用的内容。
仅限 ASCII 字符。 .sql 文件处理链中的某些环节仍会将其视为 ANSI 编码，重音符号会因此变成乱码，并永久留在数据库中。越南语不加变音符号正是出于这个原因而形成的团队风格，而且很合适。
一行
如果需要第二行，说明注释不是合适的容器。把内容移到别处：
| 你原本打算写的内容 | 应放的位置 |
|---|---|
| 为什么采用这种形式，以及没有它会出什么问题 | .sql 交付件的头部块 |
| 绝不能退化的规则 | 测试或验证器中，以带说明消息的断言实现 |
| 这个决定及你否决的备选方案 | 规范或工单 |
| 改了什么、为什么改，供查看历史的人了解 | 提交消息 |
| 这条语句的作用 | 不需要放在任何地方——语句本身已经说明了 |
只为代码无法体现的内容添加注释：陷阱、决定或缘由。
不要
- 在单条语句上方添加多行说明块。
- 添加横幅、框线图案或
-- ==== section ====。 - 添加项目符号列表、带引号的错误代码或内联修订历史。
- 将注释掉的代码留作文档。删除它——日志和 VCS 都会记住，而且它们对哪些内容仍在生效都不会撒谎。
- 修改未改动代码上的注释。这会产生另一处 diff，并掩盖你的改动。
完成前
统计你添加的注释行数。每条语句超过一行，就属于重写，而不是精简。
然后确认注释确实已写入数据库。注释恰恰是第二位写入者最容易在不知情时丢掉的内容，而且检查它毫不费力：
select count(*) from all_source
where owner = :owner and name = :name and text like :marker
预览中的 changed outside pythia 警告是这项检查的另一部分——当对象自 pythia 上次写入后发生变化时，就会触发该警告。