pythia-conventions

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Adopting a Project's Conventions

适配项目规范

Announce at start: "Using pythia-conventions — I'll read the patterns off the schema first."

Phase: Learn → Ask — derive from the schema, ask where the document disagrees, only then write the config

Conventions already exist in every mature schema. They are in the object names, in a standards document, or in a senior developer's head. This turns them into two files: patterns the tool checks on every write, and prose every future agent session reads before writing.

开始时告知："正在使用pythia-conventions——我将先从schema中提取模式。"

**阶段：**学习 → 确认 — 从schema中提取模式，确认文档与schema的差异，之后再编写配置

每个成熟的schema中都已存在规范。它们体现在对象名称、标准文档中，或是资深开发者的经验里。本工具会将这些规范转化为两个文件：工具在每次写入时都会校验的模式，以及未来所有Agent会话在写入前都会读取的说明文档。

The Iron Law

铁律

NO PATTERN WRITTEN DOWN BEFORE THE SCHEMA HAS AGREED WITH IT

A pattern that does not match the objects already there is not a convention. It is a guess that will warn on every apply until someone deletes it.

NO PATTERN WRITTEN DOWN BEFORE THE SCHEMA HAS AGREED WITH IT

与现有对象不匹配的模式不能称为规范。它只是一个猜测，会在每次应用时发出警告，直到有人将其删除。

The Workflow

工作流程

Read the shape off the database, not off your memory of it.
bash
```
pythia conventions --scan
```
It tokenises every object name and proposes a pattern per type. Do this even when a document exists — and never page through thousands of names yourself: that is what the command is for, and your context is better spent elsewhere.
Read the developer's document, if there is one. A base system's standards, a wiki page, an older project's rules. Look for what a regex cannot hold: parameter prefixes a calling layer depends on, a column every query must filter by, where a transaction may commit, which date or money representation is canonical. Those go in the prose half.
Reconcile, and say so when the two disagree. The document states intent; the schema states fact. A rule in the document that the schema contradicts is one of three things — a rule nobody follows, a rule for new code only, or drift worth reporting. Ask the developer which; do not silently pick.
Write
.pythia/conventions.json
. Start from the scan output, narrowed by the document.
```
pythia conventions --init
```
writes a blank pair if you want the skeleton first.

Verify — this step is the point of the skill.

bash

pythia conventions --check

It reports coverage per type and names what misses.

Result	What it means
every name matches	the pattern is real; keep it
~90%+ with a handful of misses	genuine exceptions — list them in step 6
below 90%	the pattern is wrong, not the schema; widen or split it, then check again
nothing of that type	an untested rule; keep it only if new objects of that type are expected

Record the exceptions, with their reason. Objects that break the rule on purpose — ported names from a base platform, legacy entry points whose names are part of a public surface. Say why renaming would cost more than the warning. An unexplained exception gets "fixed" by the next person.
Write
.pythia/conventions.md
. For every rule, state the cost of breaking it, not just the rule. "Parameter prefixes must be
```
b_
```
/
```
a_
```
" is ignorable; "the calling layer binds by prefix, so a wrong one silently unbinds the field" is not. Rules with named consequences get followed.

从数据库读取实际结构，而非凭记忆。
bash
```
pythia conventions --scan
```
该命令会将每个对象名称分词，并为每种类型推荐一个模式。即使已有文档，也要执行此操作——切勿手动翻阅数千个名称：这正是该命令的用途，你可以将精力投入到更重要的工作中。
阅读开发者提供的文档（如果有的话）。 比如基础系统的标准、wiki页面、旧项目的规则。寻找正则表达式无法涵盖的内容：调用层依赖的参数前缀、每个查询必须过滤的列、事务可提交的位置、标准的日期或金额表示方式。这些内容要写入说明文档部分。
调和差异，当两者不一致时明确提出。 文档代表意图；schema代表实际情况。文档中的规则与schema矛盾时，可能属于以下三种情况之一——无人遵循的规则、仅适用于新代码的规则，或是值得报告的偏差。询问开发者具体属于哪种情况，切勿擅自选择。
编写
.pythia/conventions.json
。从扫描输出开始，结合文档进行精简。如果需要先获取框架结构，可以使用
```
pythia conventions --init
```
生成空白文件对。

验证——这一步是该技能的核心。

bash

pythia conventions --check

该命令会按类型报告覆盖率，并列出不符合模式的对象。

结果	含义
所有名称均匹配	模式有效，保留
约90%以上匹配，仅少数不匹配	存在真实例外情况——在步骤6中列出
匹配率低于90%	模式错误，而非schema问题；放宽或拆分模式后重新检查
无该类型对象	未经过测试的规则；仅当预期会新增该类型对象时才保留

记录例外情况及原因。 故意违反规则的对象——比如从基础平台移植的名称、名称属于公共接口的遗留入口点。说明重命名的成本高于警告的原因。未说明原因的例外情况会被下一个人"修复"。
编写
.pythia/conventions.md
。对于每条规则，要说明违反规则的代价，而非仅列出规则。"参数前缀必须为
```
b_
```
/
```
a_
```
"容易被忽略；"调用层通过前缀绑定字段，错误的前缀会导致字段静默解绑"则不会。明确后果的规则才会被遵守。

Adopting from an older base the team already runs

适配团队已在使用的旧版基础系统

Point the connection at that schema and run steps 1 and 2 there — a base system with thousands of objects is the most reliable statement of a house style that exists, far better than anyone's recollection of it. Then switch the connection to the new project and run

--check

: coverage tells you how much of the base style the new schema has actually inherited.

将连接指向该schema，在那里执行步骤1和2——拥有数千个对象的基础系统是内部规范最可靠的体现，远比任何人的记忆准确。然后将连接切换到新项目并运行

--check

：覆盖率会告诉你新项目schema实际继承了多少基础系统的风格。

Red Flags — STOP if you catch yourself thinking

危险信号——如果你有以下想法，请立即停止

Thought	Reality
"I'll write the patterns from the document alone"	Documents describe intent; schemas record what happened. Scan first.
"80% coverage is good enough"	Every miss warns on every apply. Fix the pattern or record the exception.
"I'll read all the object names to work it out"	`--scan` does that without spending your context.
"The schema disagrees, so the document is wrong"	It may be a new-code-only rule. Ask.
"A rule per line is enough"	A rule without its cost is a rule people skip.

想法	实际情况
"我将仅根据文档编写模式"	文档描述的是意图；schema记录的是实际情况。先执行扫描。
"80%的覆盖率足够了"	每个不匹配的对象都会在每次应用时发出警告。要么修正模式，要么记录例外情况。
"我将阅读所有对象名称来找出模式"	`--scan` 可以完成这项工作，无需消耗你的精力。
"schema与文档不一致，所以文档是错的"	这可能是仅适用于新代码的规则。请询问清楚。
"每条规则单独列出就足够了"	没有说明代价的规则会被人们忽略。

When NOT to use this skill

何时不使用该技能

Writing one object in an existing style →
```
pythia-write
```
, which reads these files and uses
```
similar
```
for the details.
Capturing a workflow with steps and gates →
```
pythia-skill-author
```
. Naming and style belong here; procedures belong in a skill.

在现有风格下编写单个对象 → 使用
```
pythia-write
```
，该工具会读取这些文件并使用
```
similar
```
处理细节。
捕获包含步骤和关卡的工作流程 → 使用
```
pythia-skill-author
```
。命名和风格相关的内容属于本技能；流程相关的内容属于技能编写工具。