debt-ops-init

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

debt-ops-init

Write or update a

## Tech debt operations

section in the project's agent charter. Idempotent — only the managed section changes.

Run only on explicit user request ("set up debt-ops", "init debt-ops", "write the disciplines"). Do not invoke this as part of normal work. (Tools with a debt-ops hook adapter inject these disciplines per-session automatically; this skill is the persistence step for everyone else.)

在项目的Agent章程中撰写或更新

## Tech debt operations

章节。具有幂等性——仅修改受管理的章节。

仅在用户明确请求时运行（例如“set up debt-ops”、“init debt-ops”、“write the disciplines”）。请勿在常规工作中调用此工具。（带有debt-ops钩子适配器的工具会在每个会话中自动注入这些规范；本技能是为其他用户提供的持久化步骤。）

Why this matters more on skills-only tools

为什么这在仅支持技能的工具上更为重要

Without a hook adapter there is no per-edit enforcement and no automatic capture. The charter is the only place the disciplines live, so the agent self-applies them. That's "vibes," not a tripwire — be honest with the user that the persistent charter is the substitute for, not the equal of, the hook-driven write-time loop.

如果没有钩子适配器，就无法在每次编辑时进行强制检查和自动捕获。章程是这些规范的唯一存放位置，因此Agent会自行应用这些规范。这是一种“共识约束”，而非强制触发机制——请如实告知用户，持久化章程是钩子驱动的写入时循环的替代方案，而非等同方案。

1. Pick the charter file

1. 选择章程文件

Use

AGENTS.md

at the repo root — the cross-tool charter most agents read. If the project clearly standardizes on a different file your agent auto-loads (

GEMINI.md

.github/copilot-instructions.md

CLAUDE.md

), use that instead and tell the user which you picked.

使用仓库根目录下的

AGENTS.md

——这是大多数Agent都会读取的跨工具章程。如果项目明确标准化使用其他你的Agent会自动加载的文件（如

GEMINI.md

、

.github/copilot-instructions.md

、

CLAUDE.md

），则改用该文件并告知用户你的选择。

2. Read any cached quality commands (optional)

2. 读取缓存的质量检查命令（可选）

If a hook adapter previously ran in this repo, it cached the project's quality commands. Include them if present; otherwise leave the placeholder.

bash

REPO_HASH=$(python3 -c "import hashlib,subprocess;t=subprocess.run(['git','rev-parse','--show-toplevel'],capture_output=True,text=True).stdout.strip();print(hashlib.sha1(t.encode()).hexdigest()[:12] if t else '')")
CACHE_DIR="${DEBT_OPS_CACHE:-$HOME/.cache/debt-ops}/cache/$REPO_HASH"
[ -f "$CACHE_DIR/feedback.list" ] && cat "$CACHE_DIR/feedback.list"
ADR_DIR=$( [ -s "$CACHE_DIR/adr-dir" ] && cat "$CACHE_DIR/adr-dir" || echo "docs/adr" )
REGISTRY_DIR=$( [ -s "$CACHE_DIR/registry-dir" ] && cat "$CACHE_DIR/registry-dir" || echo "docs/debt" )
echo "adr-dir: $ADR_DIR"
echo "registry-dir: $REGISTRY_DIR"

If no commands are cached, detect the project's lint/type/test commands by scanning its manifests (

package.json

pyproject.toml

Cargo.toml

go.mod

Makefile

, …). Prefer commands that take a changed-file argument and run in a few seconds.

如果钩子适配器此前已在本仓库中运行过，它会缓存项目的质量检查命令。如果存在则包含这些命令；否则保留占位符。

bash

REPO_HASH=$(python3 -c "import hashlib,subprocess;t=subprocess.run(['git','rev-parse','--show-toplevel'],capture_output=True,text=True).stdout.strip();print(hashlib.sha1(t.encode()).hexdigest()[:12] if t else '')")
CACHE_DIR="${DEBT_OPS_CACHE:-$HOME/.cache/debt-ops}/cache/$REPO_HASH"
[ -f "$CACHE_DIR/feedback.list" ] && cat "$CACHE_DIR/feedback.list"
ADR_DIR=$( [ -s "$CACHE_DIR/adr-dir" ] && cat "$CACHE_DIR/adr-dir" || echo "docs/adr" )
REGISTRY_DIR=$( [ -s "$CACHE_DIR/registry-dir" ] && cat "$CACHE_DIR/registry-dir" || echo "docs/debt" )
echo "adr-dir: $ADR_DIR"
echo "registry-dir: $REGISTRY_DIR"

如果没有缓存的命令，则通过扫描项目的清单文件（

package.json

、

pyproject.toml

、

Cargo.toml

、

go.mod

、

Makefile

等）检测项目的lint/类型检查/测试命令。优先选择接受变更文件参数且能在数秒内运行的命令。

3. Compose the section (template)

3. 撰写章节内容（模板）

Substitute

{{ADR_DIR}}

{{REGISTRY_DIR}}

, and

{{COMMANDS}}

(the cached or detected commands, one per line; leave a

# add your lint/type/test commands here

placeholder if none found).

markdown

undefined

替换

{{ADR_DIR}}

、

{{REGISTRY_DIR}}

和

{{COMMANDS}}

（缓存或检测到的命令，每行一个；如果未找到则保留

# add your lint/type/test commands here

占位符）。

markdown

undefined

Tech debt operations

Disciplines

The test for debt: would a future reader ask "why this way?" If yes, register via the
```
debt-ops-add
```
skill immediately — no prompt. This is judgment, not a marker scan: a
```
TODO
```
/
```
FIXME
```
/
```
HACK
```
/
```
XXX
```
is the obvious case, but an unmade decision, a stub, a loosened type, or a default picked "for now" all count even with no marker in the diff. Use
```
payoff_trigger: unknown
```
if unsure. Announce:
```
+1 entry: <slug> (drop?)
```
. Over-register freely; the developer drops with "drop it".
When making an architecturally significant change — a data model, public interface, security boundary, release pipeline, or a dep-manifest change that is a major-version bump or a new top-level dependency — draft an ADR under
```
{{ADR_DIR}}/
```
in Nygard format: a
```
# NNNN — Title
```
heading,
```
**Date:**
```
and
```
**Status:**
```
lines, then Context, Decision, Consequences, Alternatives, Payoff trigger. Create the directory if needed. Only draft an ADR when there are two credible alternatives; if you cannot list two, it is a comment, not an ADR. An ADR with a payoff trigger is deliberate debt — when you write one, also use
```
debt-ops-add
```
so the registry entry mirrors the ADR.
Read entries under
```
{{REGISTRY_DIR}}/
```
before changing files they reference.

债务的判断标准：未来的读者是否会问“为什么要这样做？”如果是，立即通过
```
debt-ops-add
```
技能登记——无需提示。这是基于判断的，而非标记扫描：
```
TODO
```
/
```
FIXME
```
/
```
HACK
```
/
```
XXX
```
是明显的情况，但未做出的决策、存根代码、放宽的类型限制或“暂时”选择的默认值，即使差异中没有标记，也都属于技术债务。如果不确定，使用
```
payoff_trigger: unknown
```
。发布通知：
```
+1 entry: <slug> (drop?)
```
。可以过度登记；开发者可通过“drop it”来移除条目。
当进行具有架构重要性的变更时——例如数据模型、公共接口、安全边界、发布流水线，或是涉及主版本升级或新增顶级依赖的依赖清单变更——在
```
{{ADR_DIR}}/
```
下按照Nygard格式撰写ADR：包含
```
# NNNN — Title
```
标题、
```
**Date:**
```
和
```
**Status:**
```
行，然后是Context（背景）、Decision（决策）、Consequences（影响）、Alternatives（替代方案）、Payoff trigger（偿还触发条件）。如果目录不存在则创建。仅当存在两种可信的替代方案时才撰写ADR；如果无法列出两种方案，则只需添加注释，无需撰写ADR。带有偿还触发条件的ADR属于刻意的技术债务——撰写此类ADR时，同时使用
```
debt-ops-add
```
技能，以便登记条目与ADR保持一致。
在修改
```
{{REGISTRY_DIR}}/
```
下条目所引用的文件之前，请先阅读这些条目。

Quality checks

If a debt-ops hook adapter is installed (e.g. the Copilot adapter), it reads the marker block below and runs these after every edit under a 3 s budget. Without an adapter (skills-only tool), they are not enforced automatically — you, the agent, run them after editing and fix failures before moving on. Lines starting with

are estimates/comments and are skipped at run time.

undefined

如果已安装debt-ops钩子适配器（例如Copilot适配器），它会读取下方的标记块，并在每次编辑后在3秒预算内运行这些命令。如果没有适配器（仅支持技能的工具），则不会自动强制执行这些检查——你（Agent）需要在编辑后运行这些检查，并在继续操作前修复失败项。以

开头的行是估算/注释，运行时会被跳过。

undefined

4. Apply

4. 应用修改

If the charter file doesn't exist: create it with the section above as the entire file.
If it has a
## Tech debt operations
section: replace exactly that section — from the heading through (but not including) the next
```
## 
```
heading, or EOF if none. Leave every other byte unchanged.
If it exists without the section: append the section after the last line, with one blank line between.

如果章程文件不存在： 创建该文件，并将上述章节作为整个文件的内容。
如果文件已有
## Tech debt operations
章节：精确替换该章节——从标题开始，到下一个
```
## 
```
标题之前（不包含该标题），如果没有下一个
```
## 
```
标题则到文件末尾。其他内容保持不变。
如果文件存在但没有该章节： 在文件最后一行之后添加该章节，两者之间保留一个空行。

5. Announce

5. 发布通知

charter updated: <file> — disciplines + N quality commands

(N = non-comment, non-blank lines inside the marker block; 0 if placeholder).

charter updated: <file> — disciplines + N quality commands

（N为标记块内非注释、非空行的数量；如果是占位符则为0）。

Marker contract — do not deviate

```

```
is the open marker the hook adapters key on. Exact string; the
```
v1
```
is part of the marker.
```

```
is the close marker.
This must stay identical across every adapter's
```
feedback.py
```
and
```
init
```
skill — see CLAUDE.md "Adapter parity." A drift here silently breaks the Copilot write-time loop (it reads the block by this exact marker).

```

```
是钩子适配器识别的起始标记。字符串必须完全一致；
```
v1
```
是标记的一部分。
```

```
是结束标记。
所有适配器的
```
feedback.py
```
和
```
init
```
技能中的此标记必须保持完全一致——请参阅CLAUDE.md中的“Adapter parity”（适配器一致性）。此处的差异会静默破坏Copilot的写入时循环（它通过此精确标记读取块内容）。

Don't

Don't auto-invoke. Only on explicit user request.
Don't touch any byte outside the
```
## Tech debt operations
```
section.
Don't claim the charter gives deterministic enforcement — it doesn't without a hook adapter. Say so.

请勿自动调用。仅在用户明确请求时运行。
请勿修改
```
## Tech debt operations
```
章节之外的任何内容。
请勿声称章程能提供确定性的强制约束——没有钩子适配器的话是做不到的。请如实说明。