debt-ops — плагин для Claude Code: что делает и как установить
Плагин debt-ops для Claude Code и Codex записывает отложенные решения агента в реестр репозитория; скилл ревью сортирует долги по частоте правок файлов.
MIT ★ 1 596 обновлён 2026-10-29
/plugin marketplace add hashgraph-online/awesome-codex-plugins
/plugin install debt-ops@awesome-codex-pluginsЧто делает debt-ops
Плагин вешает хуки на каждый шаг агента. SessionStart подсовывает дисциплины и кэширует команды проверки качества вместе с путями к ADR и реестру. После apply_patch, Edit или Write хук PostToolUse прогоняет эти команды по изменённым файлам с бюджетом 3 секунды на команду. Stop ищет свежие TODO и напоминает, если отложенное решение так и не попало в реестр.
Сами записи лежат в репозитории. Скилл $add заводит долг и выдаёт ему букву партии, $review разбирает реестр и сортирует, что гасить первым, по частоте правок файла, $metrics печатает сводку из лога. Ещё есть $init: он пишет в AGENTS.md раздел ## Tech debt operations, откуда хуки читают команды качества. Именно AGENTS.md, а не CLAUDE.md, потому что это адаптер под Codex.
Нужен git-репозиторий и Python 3.10+, причём только стандартная библиотека: без репозитория реестру негде лежать. Кэш живёт в ~/.cache/debt-ops/cache/<repo-hash>/, другой путь задаётся через DEBT_OPS_CACHE. В Codex можно писать в промпте drop A, drop A,C или drop all, а DEBT_OPS_DEBUG=1 складывает лог каждого срабатывания хука в файл в кэше.
Какие задачи решает
- поймать отложенное решение агента в момент правки
- свести все долги в один реестр внутри репозитория
- отсортировать, что чинить первым, по частоте правок файла
- не забыть вернуться к TODO, оставшимся в коде
- снять сводку по накопленному долгу перед рефакторингом
Примеры запросов агенту
- Занеси в реестр: заглушка в
billing/tax.py, вернуться после релиза —$add - Покажи, что гасить первым:
$review - Сколько долгов накопилось? Дай сводку:
$metrics
Как установить debt-ops
Через маркетплейс плагинов
/plugin marketplace add hashgraph-online/awesome-codex-plugins/plugin install debt-ops@awesome-codex-pluginsПо шагам, с командами для каждой платформы: Плагины Claude Code: маркетплейсы, установка и как собрать свой
Вопросы о debt-ops
Как установить debt-ops в Claude Code?
Две команды по порядку: /plugin marketplace add hashgraph-online/awesome-codex-plugins, затем /plugin install debt-ops@awesome-codex-plugins.
Что делает debt-ops?
Логирует технический долг, который создаёт кодинг-агент, в реестр внутри репозитория. Потом $review сортирует записи по частоте правок файлов, чтобы было видно, что гасить первым.
Чем версия для Codex отличается от Claude?
Устав пишется в AGENTS.md, а не в CLAUDE.md, и хуки читают команды качества оттуда. Правки приходят как apply_patch, скиллы вызываются через $add, $review, $init и $metrics.
Исходный текст
agentic-tech-debt · MIT
# debt-ops — Codex adapter
The [debt-ops](../README.md) disciplines, packaged as a [Codex](https://developers.openai.com/codex) plugin. Behavior matches the [Claude Code adapter](../claude-code); this README covers only what's Codex-specific.
## Install
Register the marketplace from your shell, then install from the plugin browser:
```bash
codex plugin marketplace add bcanfield/agentic-tech-debt
```
Open `/plugins` inside Codex and install **debt-ops**. Working *inside* this repo, Codex auto-discovers the bundled marketplace at `.agents/plugins/marketplace.json` once the project is trusted — no add step needed. Requires a git repo and Python 3.10+ (stdlib only).
## What's wired
Layout follows Codex's plugin conventions: hooks bundle their scripts under `hooks/` (referenced via `${PLUGIN_ROOT}/hooks/…`), and each skill bundles its helper under its own `scripts/` (referenced by a relative path, the documented skill convention).
| Codex primitive | File | Role |
| --- | --- | --- |
| `SessionStart` hook | `hooks/session-start.py` | Injects the disciplines + detects/caches quality commands and ADR/registry dirs |
| `PostToolUse` hook (`apply_patch\|Edit\|Write`) | `hooks/feedback.py` | Runs quality commands on edited files under a 3s/command budget |
| `Stop` hook | `hooks/stop.py` | TODO-sniff safety net — nudges when deferrals went unregistered |
| `UserPromptSubmit` hook | `hooks/drop.py` | Handles `drop A` / `drop A,C` / `drop all` shorthand |
| `$add` skill | `skills/add/` (+ `scripts/register.py`) | Registers a debt entry, assigns a batch letter |
| `$review` skill | `skills/review/` (+ `scripts/review.py`) | Audits + ranks the registry; walks paydown |
| `$init` skill *(explicit-only)* | `skills/init/` | Writes the `## Tech debt operations` charter into `AGENTS.md` |
| `$metrics` skill | `skills/metrics/` | Read-only health summary from the metrics log |
## Codex-specific notes
- **Charter file is `AGENTS.md`**, not `CLAUDE.md` — `$init` writes the managed `## Tech debt operations` section there, and the hooks read quality commands from it.
- **Edits are `apply_patch`.** The feedback hook parses the V4A patch envelope (`*** Add/Update File:`, `*** Move to:`) to learn which files changed, since there's no `tool_input.file_path`.
- **Cache** lives at `~/.cache/debt-ops/cache/<repo-hash>/` (override with `DEBT_OPS_CACHE`) so the hooks and skill Bash always agree on one path ([ADR 0012](../docs/adr/0012-codex-deterministic-cache-base.md)).
- **Skill invocation** is `$add` / `$review` / `$init` / `$metrics` (or the `/skills` picker). `$init` is explicit-only (`skills/init/agents/openai.yaml`).
- **Debug:** set `DEBT_OPS_DEBUG=1` to log every hook fire to `<cache>/debug.log`.
## Research
Disciplines map to the [nine tool-agnostic pillars](../docs/tech-debt-pillars.md); the [Claude Code mapping](../docs/tech-debt-plugin-plan.md) explains why each hook exists. Same evidence base, different agent.
© Brandin Canfield · MIT · hashgraph-online/awesome-codex-plugins