fitness-config-init

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Fitness Config Init

Fitness Config 初始化

Create

fitness-config.json

for a project so the review skills weigh what matters for it. A database backend should count reliability and data heavily and accessibility barely at all. A public website should count accessibility first. This skill works out which kind of project it is looking at, proposes weights from a matching profile, and saves them only after the user has seen the proposal.

The weights themselves live in

references/purpose-profiles.md

and in the resolver. This file never states a weight. Always take numbers from the resolver output or the profile table.

为项目创建

fitness-config.json

，让评审 skill 根据项目实际情况衡量真正重要的方面。数据库后端应高度看重可靠性和数据，几乎不看可访问性。公共网站则应把可访问性放在首位。此 skill 会判断当前面对的是哪一类项目，从匹配的用途画像出发提出权重，并且只在用户看过提案后保存。

权重本身定义在

references/purpose-profiles.md

和 resolver 中。此文件绝不规定具体权重。始终从 resolver 输出或画像表中获取数值。

References

参考资料

```
references/purpose-signals.md
```
: what to read in the fast scan, the 40-file budget, signals per archetype, and what high, medium and low confidence mean.
```
references/purpose-profiles.md
```
: the six archetype profiles, the rules for adjusting them, and typical rationale for each.

Read both before step 3.

```
references/purpose-signals.md
```
：快速扫描时应读取哪些内容、40 个文件的读取上限、各原型对应的信号，以及高、中、低置信度的含义。
```
references/purpose-profiles.md
```
：六种原型画像、调整规则，以及每种画像的典型理由。

在步骤 3 前阅读这两份文件。

Resolver

Every config read and write goes through the resolver CLI. Never load

fitness-config.json

yourself and never write it with a file tool.

bash

python3 "${CLAUDE_SKILL_DIR}/../../scripts/fitness-config.py" <command>

${CLAUDE_SKILL_DIR}

is this skill's directory; the resolver ships two levels up in the plugin's

scripts/

. If your agent does not expand the variable, substitute the directory containing this

SKILL.md

Run every resolver command from the anchor: the git top-level of the target (

git -C <target> rev-parse --show-toplevel

), or the target itself when it is not in a git repository. Pass the target relative to the anchor. Set

PYTHONDONTWRITEBYTECODE=1

so running the resolver does not leave

__pycache__

beside it.

Purpose	Command
Starting config (baseline)	`init --path <target> --dry-run`
Current values of an existing config	baseline JSON piped to `init --path <target> --from - --dry-run`
Check a proposal, get its fingerprint	`init --path <target> --from - --dry-run` (proposal JSON on stdin)
Save a reviewed proposal	`init --path <target> --from - --expect <fingerprint>` (same JSON on stdin)
Confirm what applies after saving	`show --path <target>`

每次读取和写入配置都必须通过 resolver CLI 完成。绝不自行加载

fitness-config.json

，也绝不使用文件工具写入它。

bash

python3 "${CLAUDE_SKILL_DIR}/../../scripts/fitness-config.py" <command>

${CLAUDE_SKILL_DIR}

是此 skill 所在的目录；resolver 随插件提供，位于

scripts/

目录下两层之上。如果你的 Agent 无法展开该变量，则改用包含此

SKILL.md

的目录。

所有 resolver 命令都必须从锚点运行：即目标的 git 顶层（

git -C <target> rev-parse --show-toplevel

），如果目标不在 git 仓库中，则以目标自身为锚点。传入相对于锚点的目标路径。设置

PYTHONDONTWRITEBYTECODE=1

，以免运行 resolver 时在其旁边留下

__pycache__

。

用途	命令
起始配置（基线）	`init --path <target> --dry-run`
现有配置的当前值	将基线 JSON 通过管道传给 `init --path <target> --from - --dry-run`
检查提案并获取其指纹	`init --path <target> --from - --dry-run` （提案 JSON 从标准输入传入）
保存已审阅的提案	`init --path <target> --from - --expect <fingerprint>` （传入同一份 JSON）
确认保存后生效的内容	`show --path <target>`

Workflow

工作流

Step 0: Target and probe

步骤 0：目标与探测

The target is the path argument, or the current folder. Print it as the first line of output:
```
Target: <absolute path>
```
.
Find the anchor. If there is no git repository, say "No repository found; ancestor configs not considered."
Run
```
init --path <target> --dry-run
```
. It writes nothing. Relay its header lines verbatim (
```
STATUS:
```
,
```
Baseline-Source:
```
and any chain lines) and keep the canonical JSON block as the baseline. The baseline is the built-in starting config at the repository root, or the merged parent configs for a subfolder.
If the probe exits 2 saying the target is not a folder or does not exist, stop and tell the user; do not use degraded mode.
If the probe fails otherwise (no
```
python3
```
, the path did not expand, the resolver errors), switch to degraded mode: read
```
${CLAUDE_SKILL_DIR}/../../fitness-config.example.json
```
as the baseline, label it "example file (degraded)", and continue through step 5 printing the proposal for manual use. Degraded mode never saves. If the example file is also unreachable, stop and say why.
Existing config (skip in degraded mode). The baseline ignores a
```
fitness-config.json
```
already at the target, but the step 5 diff compares against it. So that the table and the diff agree, pipe the baseline JSON to
```
init --path <target> --from - --dry-run
```
(writes nothing):
- ```
would-create
```
  : no config yet. The table has no current column.
- ```
would-replace
```
  : each diff line
```
path old -> new
```
  gives a current value (
```
old
```
  ); every path not listed equals the baseline. Add a current column to the table in step 4.
- ```
unchanged
```
  : the existing file equals the baseline. Say so; no current column.
- ```
existing-malformed
```
  : say the existing file is not valid JSON; the current column reads
```
malformed
```
  .
- ```
existing-not-a-file
```
  : relay the error and stop; nothing can be saved there.

目标是路径参数或当前文件夹。将它作为输出的第一行打印：
```
Target: <absolute path>
```
。

查找锚点。如果不存在 git 仓库，则说：

No repository found; ancestor configs not considered.

运行
```
init --path <target> --dry-run
```
。它不会写入任何内容。原样转发其头部行（
```
STATUS:
```
、
```
Baseline-Source:
```
以及任何链式行），并将规范 JSON 块保留为基线。基线是仓库根目录的内置起始配置，或是子文件夹合并父级配置后的结果。
如果探测以状态码 2 退出，并提示目标不是文件夹或不存在，则停止并告知用户；不要使用降级模式。
如果探测因其他原因失败（没有
```
python3
```
、路径未展开、resolver 报错等），切换到 降级模式：读取
```
${CLAUDE_SKILL_DIR}/../../fitness-config.example.json
```
作为基线，将其标记为
```
example file (degraded)
```
，然后继续执行到步骤 5，打印供手动使用的提案。降级模式绝不保存配置。如果示例文件也无法访问，则停止并说明原因。
现有配置（在降级模式下跳过）。基线会忽略目标中已经存在的
```
fitness-config.json
```
，但步骤 5 的差异比较会以它为比较对象。因此，为使表格和差异保持一致，将基线 JSON 通过管道传给
```
init --path <target> --from - --dry-run
```
（不会写入任何内容）：
- ```
would-create
```
  ：尚不存在配置。表格不包含“当前值”列。
- ```
would-replace
```
  ：每一行差异
```
path old -> new
```
  给出一个当前值（
```
old
```
  ）；未列出的每个路径都等于基线。在步骤 4 的表格中添加“当前值”列。
- ```
unchanged
```
  ：现有文件与基线相同。说明这一点；不添加“当前值”列。
- ```
existing-malformed
```
  ：说明现有文件不是有效 JSON；“当前值”列显示
```
malformed
```
  。
- ```
existing-not-a-file
```
  ：转发错误并停止；无法在该位置保存任何内容。

Step 1: Evidence mode

步骤 1：证据模式

fast (default): a read-only scan of at most 40 files.
full: runs
```
review-full
```
on the target first, then the fast scan.

Take the mode from the argument only if it is exactly

fast

full

. Otherwise use the request text: it means full only if it says "full review", "full mode" or "run review-full" and does not also say "fast" or "quick"; it means fast if it says "fast" or "quick" and nothing about full. In every other case, ask

Evidence mode: fast scan or full review? [fast]

and treat Enter as fast. Never upgrade to full on your own.

Before a full review, warn and wait for a yes: "A full review runs every review skill and writes

docs/fitness-report.md

into the project. Continue? [y/N]". Anything other than

yes

falls back to fast.

fast（默认）：只读扫描最多 40 个文件。
full：先对目标运行
```
review-full
```
，然后再进行快速扫描。

仅当参数恰好为

fast

或

full

时，才从参数中采用模式。否则根据请求文本判断：只有当请求中包含“full review”“full mode”或“run review-full”，并且没有同时提到“fast”或“quick”时，才使用 full；只有当请求中提到“fast”或“quick”且没有涉及 full 时，才使用 fast。在所有其他情况下，询问：

Evidence mode: fast scan or full review? [fast]

，并将按下 Enter 视为 fast。绝不要自行升级到 full。

在完整评审之前，警告用户并等待其回答 yes：

A full review runs every review skill and writes docs/fitness-report.md into the project. Continue? [y/N]

。除

或

yes

外的任何回答都回退到 fast。

Step 2: Gather evidence

步骤 2：收集证据

Fast: follow the scan order in
```
references/purpose-signals.md
```
. Stay within 40 file reads. Do not run project code or use the network. Do not change any file.
Full: run the
```
review-full
```
skill with its scope set explicitly to the target folder (never the default of pending changes), then do the fast scan as well. Read
```
docs/fitness-report.md
```
afterwards:
- If its
```
**Scope:**
```
  line shows that only pending changes were reviewed (not the target folder), drop all full review evidence and tell the user: "The full review only covered pending changes, so its results were not used."
- If a domain failed or has no parsable row, use fast scan evidence for that domain only and say so. The other domains keep their full review evidence.

Each evidence item is a path that a read or list tool returned, a short note on what it shows, and its source (

fast

review-full

Fast：按照
```
references/purpose-signals.md
```
中的扫描顺序执行。最多读取 40 个文件。不要运行项目代码或使用网络。不要修改任何文件。
Full：运行
```
review-full
```
skill，并将范围明确设为目标文件夹（绝不能使用默认的待处理变更范围），然后再进行快速扫描。之后读取
```
docs/fitness-report.md
```
：
- 如果其
```
**Scope:**
```
  行表明只评审了待处理变更（而非目标文件夹），则丢弃所有完整评审证据，并告知用户：
```
The full review only covered pending changes, so its results were not used.
```
- 如果某个领域失败或没有可解析的行，则只对该领域使用快速扫描证据，并说明这一点。其他领域继续使用完整评审证据。

每条证据都包含：读取或列举工具返回的路径、对该路径所显示内容的简短说明，以及来源（

fast

或

review-full

）。

Step 3: Classify the purpose

步骤 3：对用途进行分类

Classify as one archetype from

references/purpose-profiles.md

mixed

, or

unknown

, with a confidence level from

references/purpose-signals.md

. Show the purpose in plain words, the archetype, the confidence and the evidence list.

A purpose stated in the request is the user's answer. If the request already says what the project is ("it's my shell tool", "for this public website", "our payments API"), map it to an archetype and set the confidence to

user-confirmed

. Show the classification line with

confidence: user-confirmed (stated in request)

and go on to step 4 without asking. The scan still runs, because moves away from the profile need evidence. If the scan points strongly at a different archetype, say so in one line, but use the stated purpose. Ask only when the statement fits no archetype or fits two.

high or user-confirmed: go on to step 4.
medium or mixed: ask "What is the primary purpose of this project?" and offer the archetypes. For a mixed repository, add that a subfolder can get its own config later by running this skill on that folder. Do not create one.
low or unknown: ask the same question once. With no answer, say "Kept baseline: not enough evidence to tune." and propose the baseline unchanged, with no reasons.

If the user corrects the classification, use their answer without argument.

根据

references/purpose-profiles.md

，将用途分类为一种原型、

mixed

或

unknown

，并按照

references/purpose-signals.md

确定置信度。用通俗语言说明用途、原型、置信度和证据列表。

请求中说明的用途就是用户的答案。 如果请求已经说明项目是什么（“这是我的 shell 工具”“用于这个公共网站”“这是我们的支付 API”），将其映射到一种原型，并把置信度设为

user-confirmed

。显示如下分类行：

confidence: user-confirmed (stated in request)

，然后继续执行步骤 4，不再询问。扫描仍需执行，因为偏离画像的调整需要证据。如果扫描结果强烈指向另一种原型，用一行说明，但仍采用用户声明的用途。只有当声明不适用于任何原型或同时适用于两种原型时才询问。

high 或 user-confirmed：继续执行步骤 4。
medium 或 mixed：询问
```
What is the primary purpose of this project?
```
，并提供可选原型。对于混合仓库，补充说明：之后可以在该子文件夹上运行此 skill，为其创建单独的配置。不要立即创建。
low 或 unknown：只询问一次同样的问题。如果没有回答，则说明
```
Kept baseline: not enough evidence to tune.
```
，并原样提出基线，不提供调整理由。

如果用户纠正了分类结果，直接采用用户的答案，不再争辩。

Step 4: Propose

步骤 4：提出方案

Start from the archetype's row in
```
references/purpose-profiles.md
```
. The profile is the reference point for judgment (ADR-007): the classification evidence from step 3 justifies the whole row, so a value taken unchanged from the profile needs no evidence of its own.
Adjust using this project's evidence, following the rules in that file: no more than 4 points per domain from the profile, a cited reason for every move away from the profile, whole numbers of at least 1, total of 100. Full review results only lower domains that do not apply; a low score never raises a weight.
Build the complete proposal: the baseline JSON with the
```
weights
```
section replaced. Keep
```
statusThresholds
```
,
```
security
```
and
```
scoring
```
from the baseline unless the evidence shows higher stakes (payments, credentials, personal data). Change a threshold only with a stated reason citing that evidence, and add a row for it to the table below. For an ordinary project, keep the starting thresholds and say there is no stakes signal to change them. The status bands must cover every score from 1 to 10 once, with no gap or overlap; the security cutoff stays between 1 and 10.
Print the rationale table, one row per weight in resolver order, then one row per changed threshold. Add the current column only when step 0 found an existing config:
key current baseline profile proposed reason
weights.<domain>
existing file from baseline from profile row from proposal see below
The reason column has exactly one entry per row. Check these in order:
- proposed differs from profile:
```
profile ±N: <evidence path> <what it shows>
```
  , where N is at most 4, or
```
user edit
```
  for a change the user asked for. This is the only kind of reason that needs its own evidence, even when the move lands back on the baseline value.
- proposed equals profile and differs from baseline:
```
<archetype> profile
```
  . The classification evidence from step 3 covers it.
- proposed equals profile and baseline:
```
(unchanged)
```
  .
With no profile (unknown, kept baseline), leave the profile column as
```
-
```
and every reason
```
(unchanged)
```
. For a threshold row, the profile column is
```
-
```
and the reason cites the stakes evidence. Keep each reason under about 100 characters. Count and show the moves away from the profile, for example
```
Moves from profile: 3 (each within 4)
```
.
Show the total. Apply any change the user asks for ("raise X, take it from Y"), rebalance to 100, and print the table again.

key	current	baseline	profile	proposed	reason
`weights.<domain>`	existing file	from baseline	from profile row	from proposal	see below

The rationale is printed only. It is never written into the config file.

从
```
references/purpose-profiles.md
```
中对应原型的行开始。该画像是判断的参考点（ADR-007）：步骤 3 的分类证据足以支撑整行画像，因此从画像中原样采用的值无需单独提供证据。
使用本项目的证据进行调整，并遵循该文件中的规则：每个领域相对画像最多偏离 4 分；每次偏离画像都必须引用理由；所有值均为至少 1 的整数，总和为 100。完整评审结果只能下调不适用的领域；低分绝不能提高权重。
基于基线 JSON 构建完整提案，仅替换
```
weights
```
部分。除非证据显示风险更高（支付、凭据、个人数据），否则保留基线中的
```
statusThresholds
```
、
```
security
```
和
```
scoring
```
。只有在给出引用该证据的理由后才能更改阈值，并须在下表中为其添加一行。对于普通项目，保留初始阈值，并说明没有需要更改阈值的风险信号。状态区间必须恰好覆盖 1 到 10 的每个分数一次，不得有空缺或重叠；安全分界线保持在 1 到 10 之间。
按 resolver 顺序为每个权重打印一行理由表，然后为每个已更改的阈值打印一行。仅当步骤 0 发现现有配置时添加“当前值”列：
key 当前值基线画像提案理由
weights.<domain>
现有文件来自基线来自画像行来自提案见下文
“理由”列的每一行必须恰好包含一项内容。按以下顺序检查：
- 提案值不同于画像值：
```
profile ±N: <evidence path> <what it shows>
```
  ，其中 N 最多为 4；对于用户要求进行的更改，使用
```
user edit
```
  。只有这类理由需要提供独立证据，即使调整后的值最终回到基线值也是如此。
- 提案值等于画像值但不同于基线值：
```
<archetype> profile
```
  。步骤 3 的分类证据已经涵盖此项。
- 提案值同时等于画像值和基线值：
```
(unchanged)
```
  。
如果没有画像（用途为 unknown 并保留基线），将画像列设为
```
-
```
，每项理由都设为
```
(unchanged)
```
。对于阈值行，画像列同样设为
```
-
```
，理由中引用风险证据。每项理由应控制在约 100 个字符以内。统计并显示偏离画像的次数，例如：
```
Moves from profile: 3 (each within 4)
```
。
显示总和。应用用户要求的任何更改（“提高 X，从 Y 中扣除”），重新平衡到 100，然后再次打印表格。

key	当前值	基线	画像	提案	理由
`weights.<domain>`	现有文件	来自基线	来自画像行	来自提案	见下文

理由表只用于打印，绝不写入配置文件。

Step 5: Check the proposal

步骤 5：检查提案

Pipe the proposal JSON to

init --path <target> --from - --dry-run

. This writes nothing.

Relay the
```
STATUS:
```
and
```
Proposal:
```
lines verbatim and show the canonical JSON block exactly as printed. The
```
Proposal:
```
value is the fingerprint.
```
STATUS: invalid
```
: show each error line, fix the proposal, and run the check again.

STATUS: would-create

: ask "Save this as

<target>/fitness-config.json

? [y/N]".

```
STATUS: would-replace
```
: a config already exists. Show every diff line the resolver printed (
```
path old -> new
```
, then
```
(N values unchanged)
```
); each
```
old
```
matches the current column of the table. Then ask "Overwrite
```
<target>/fitness-config.json
```
? [y/N]".
```
STATUS: existing-malformed
```
: the current file is not valid JSON, so there is no diff. Say so, show the proposal, and ask the same overwrite question.
```
STATUS: unchanged
```
: the current config already equals the proposal. Say there is nothing to save and skip to step 7.
```
STATUS: existing-not-a-file
```
: something other than a file (such as a folder) is at
```
<target>/fitness-config.json
```
. Relay the error and stop; nothing can be saved there until the user moves it.

将提案 JSON 通过管道传给

init --path <target> --from - --dry-run

。这不会写入任何内容。

原样转发
```
STATUS:
```
和
```
Proposal:
```
行，并完全按打印结果显示规范 JSON 块。
```
Proposal:
```
的值就是指纹。
```
STATUS: invalid
```
：显示每一行错误，修复提案，然后重新检查。

STATUS: would-create

：询问

Save this as <target>/fitness-config.json? [y/N]

。

```
STATUS: would-replace
```
：配置已经存在。显示 resolver 打印的每一行差异（
```
path old -> new
```
，然后是
```
(N values unchanged)
```
）；每个
```
old
```
都应与表格中的“当前值”一致。然后询问
```
Overwrite <target>/fitness-config.json? [y/N]
```
。
```
STATUS: existing-malformed
```
：当前文件不是有效 JSON，因此没有差异。说明这一点，展示提案，并询问相同的覆盖问题。
```
STATUS: unchanged
```
：当前配置已经与提案相同。说明无需保存，并跳至步骤 7。
```
STATUS: existing-not-a-file
```
：
```
<target>/fitness-config.json
```
处存在非文件内容（例如文件夹）。转发错误并停止；在用户移走该内容之前，无法在此处保存任何内容。

Step 6: Save

步骤 6：保存

Only an answer of

yes

(any case) is a go-ahead. Anything else, including an empty answer, means No: say nothing was written and stop.

After a go-ahead for
```
would-create
```
, pipe the same JSON to
```
init --path <target> --from - --expect <fingerprint>
```
with the fingerprint from step 5.
After a go-ahead to overwrite (
```
would-replace
```
or
```
existing-malformed
```
), pipe the same JSON to
```
init --path <target> --from - --expect <fingerprint> --force
```
. The resolver replaces the file atomically and puts the old bytes back if the check after writing fails.
```
STATUS: created
```
or
```
replaced
```
: go to step 7.
```
STATUS: unchanged
```
: the file already held this config and was not touched. Go to step 7.
```
STATUS: fingerprint-mismatch
```
: the JSON changed since the check. Run step 5 again and ask again.
```
STATUS: refused-exists
```
: a config appeared since the check. Stop; nothing was written.
```
STATUS: verify-failed-rolled-back
```
or any other failure: report "not written" with the resolver's message.

Pass

--force

only after the user said yes to the overwrite question for this fingerprint. Never save a proposal the user has not seen and approved.

只有回答

或

yes

（不区分大小写）才表示同意。其他任何回答，包括空回答，都表示 No：说明未写入任何内容并停止。

用户同意
```
would-create
```
后，将 同一份 JSON 通过管道传给
```
init --path <target> --from - --expect <fingerprint>
```
，其中的指纹来自步骤 5。
用户同意覆盖（
```
would-replace
```
或
```
existing-malformed
```
）后，将 同一份 JSON 通过管道传给
```
init --path <target> --from - --expect <fingerprint> --force
```
。resolver 会原子性地替换文件；如果写入后的检查失败，则会恢复旧字节。
```
STATUS: created
```
或
```
replaced
```
：继续执行步骤 7。
```
STATUS: unchanged
```
：文件已经包含此配置，未作改动。继续执行步骤 7。
```
STATUS: fingerprint-mismatch
```
：JSON 在检查后发生了变化。重新执行步骤 5，并再次征求用户同意。
```
STATUS: refused-exists
```
：检查后出现了新配置。停止操作；未写入任何内容。
```
STATUS: verify-failed-rolled-back
```
或任何其他失败：按照 resolver 的消息报告
```
not written
```
。

只有当用户针对此指纹明确同意覆盖后，才能传入

--force

。绝不保存用户尚未看到和批准的提案。

Step 7: Summarize

步骤 7：总结

Run
```
show --path <target>
```
and relay its
```
Config:
```
line verbatim.
If that line names more than one file, say: "This config applies to
```
<target>
```
and below. Parent configs still apply where this file does not set a value."
Repeat the rationale table from step 4 exactly as shown.
Suggest the next step: run
```
review-full
```
to get a fitness report with the new weights.

运行
```
show --path <target>
```
，并原样转发其中的
```
Config:
```
行。

如果该行列出了多个文件，则说明：

This config applies to <target> and below. Parent configs still apply where this file does not set a value.

完全按照步骤 4 中的显示方式再次输出理由表。
建议下一步操作：运行
```
review-full
```
，使用新权重生成 fitness 报告。

Rules

规则

Nothing in the project changes before step 6, except
```
docs/fitness-report.md
```
in full mode after the user agreed.
Every weight shown comes from the resolver output or
```
references/purpose-profiles.md
```
.
Every move away from the profile, and every threshold change, cites evidence that exists in the target.
Never create per-folder configs the user did not ask for.

在步骤 6 之前，项目中不会发生任何更改；唯一例外是用户同意后，在 full 模式下生成
```
docs/fitness-report.md
```
。
显示的每个权重都来自 resolver 输出或
```
references/purpose-profiles.md
```
。
每次偏离画像的调整以及每次阈值更改，都必须引用目标项目中确实存在的证据。
绝不创建用户未要求的子文件夹配置。