mcpField
P
pythia-conventions

pythia-conventions

github.com/thaildhe172591数据与数据库4116 次安装5 天前更新
代码仓库

关于 pythia-conventions

pythia-conventions 是用于借助 pythia 制定并检查项目命名与 lint 约定的技能。它从数据库架构中提取模式，与书面规范核对，并在记录规则前验证覆盖情况。

主要功能

  1. 01扫描架构对象名称
  2. 02核对架构与书面规范
  3. 03初始化约定文件
  4. 04检查命名规则覆盖率
  5. 05配置机器检查的 lint 规则

适用场景

  1. 01从成熟架构中采用约定
  2. 02应用更改前验证命名模式
  3. 03记录旧命名例外
  4. 04执行项目专属 lint 规则

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/thaildhe172591/pythia --skill pythia-conventions

安装后在 Claude Code 中输入/pythia-conventions确认已加载。

详细介绍

采用项目约定

开始时说明：“正在使用 pythia-conventions——我会先从架构中读取模式。”

**阶段：**学习 → 询问 — 从架构中推导，在文档不一致处询问，然后再编写配置

每个成熟的架构中都已有约定。它们体现在对象名称、标准文档或资深开发者的脑海中。本流程会将其整理为两个文件：一个记录工具每次写入时都会检查的模式，另一个记录供今后每次 Agent 会话在写入前阅读的说明。

铁律

NO PATTERN WRITTEN DOWN BEFORE THE SCHEMA HAS AGREED WITH IT

如果某个模式与已有对象不匹配，那就不是约定，而是猜测；它会在每次应用时都发出警告，直到有人将其删除。

工作流

  1. 从数据库中读取实际情况，不要凭记忆判断。

    pythia conventions --scan

    它会对每个对象名称进行分词，并按类型提出模式。即使已有文档，也要执行这一步；千万不要自己逐页查看成千上万个名称：这正是该命令的用途，你的上下文最好留给其他事情。

  2. **阅读开发者的文档（如果有）。**基础系统的标准、Wiki 页面、旧项目的规则都可以。留意正则表达式无法表达的内容：调用层依赖的参数前缀、每个查询都必须筛选的列、事务可以提交的位置、规范的日期或金额表示方式。这些内容应写入说明部分。

  3. **核对差异，并在两者不一致时明确指出。**文档说明意图；架构反映事实。如果架构与文档中的规则相矛盾，可能有三种情况：没人遵循这条规则、这条规则只适用于新代码，或者存在值得报告的偏差。询问开发者是哪一种，不要默默自行决定。

  4. **编写 .pythia/conventions.json。**以扫描结果为基础，再根据文档缩小范围。如果想先生成骨架，可以运行 pythia conventions --init 创建一组空文件。

  5. 验证——这一步正是此技能的重点。

    pythia conventions --check

    它会报告每种类型的覆盖率，并列出不匹配的名称。

    结果含义
    所有名称都匹配模式确实成立；保留它
    约 90% 以上匹配，只有少数不匹配确实存在例外——在第 6 步中列出
    低于 90%模式有误，而不是架构有问题；扩大或拆分模式，然后再次检查
    没有该类型的对象规则尚未经过测试；只有预计会新增此类对象时才保留

  6. **记录例外，并说明原因。**有意违反规则的对象——从基础平台移植来的名称、名称属于公共接口的旧入口点。说明重命名为何比接受警告代价更高。没有说明的例外会被下一位处理者“修复”。

  7. 编写 .pythia/conventions.md。对每条规则，都要说明违反规则的代价，而不只是规则本身。“参数前缀必须是 b_/a_”很容易被忽略；“调用层会根据前缀绑定，因此前缀错误会导致字段静默地无法绑定”则不会。有明确后果的规则才会得到遵循。

由 LEAD 规则进行机器检查：lint 块

正则表达式无法检查、但 linter 可以检查的规则，应与 naming 一起写入 conventions.json——此后每次运行 pythia lint 和应用预览时都会检查这些规则，autopilot 也不会提交 error：

"lint": {
  "rules": {"varchar2-byte-semantics": "error", "dbms-output": "off"},
  "require_comments": "error",
  "required_columns": ["CREATED_BY", "CREATED_AT"],
  "param_prefix": "^P_",
  "forbid": [{"id": "no-sysdate", "pattern": "\\bSYSDATE\\b",
              "message": "use SYSTIMESTAMP", "severity": "warning"}]
}

严重级别：off、info、warning、error。pythia lint --json 会列出所有内置规则 ID。衡量新规则时，采用与命名模式相同的方法：对少量现有对象运行 lint（将 pythia src 的输出写入文件）——如果一条规则对整个代码库都会触发，那它就只适用于新代码，并且要明确说明。

从团队已在使用的旧基础项目中采用约定

将连接指向该架构，并在那里执行第 1 步和第 2 步——包含成千上万个对象的基础系统，是了解现存项目规范最可靠的依据，远胜于任何人的回忆。然后将连接切换到新项目并运行 --check：覆盖率会告诉你，新架构实际继承了多少基础项目的规范。

危险信号 — 如果发现自己有以下想法，请立即停止

想法现实情况
“我只看文档就能写出这些模式”文档描述意图；Schema 记录实际发生的情况。先扫描。
“覆盖率达到 80% 就够了”每次应用时，每个遗漏项都会发出警告。修正模式或记录例外。
“我会把所有对象名称都读一遍，弄清楚情况”--scan 就能做到，而且不会占用你的上下文。
“Schema 不一致，所以文档错了”这可能是仅适用于新代码的规则。请确认。
“每行一条规则就够了”不说明代价的规则，人们会跳过。

何时不应使用此技能

  • 按现有风格编写单个对象 → 使用 pythia-write，它会读取这些文件，并使用 similar 处理细节。
  • 记录包含步骤和关卡的工作流 → 使用 pythia-skill-author。 命名和风格属于这里；流程则属于技能。

评论

支持 Markdown