К основному содержанию
скилл CX Codex

adr-code-traceability — скилл для Claude Code: ссылки на ADR в коде

Скилл adr-code-traceability для Claude Code добавляет ссылки на Architecture Decision Records в заголовки новых файлов и комментарии к нетривиальным решениям. Связывает код с архитектурным решением.

MIT 144 установок ★ 3 обновлён 2026-10-25

Установить в Claude Code · Через Skills CLI (Vercel) Все способы и платформы ↓
npx skills add terrylica/cc-skills --skill adr-code-traceability -a claude-code
Открыть на GitHub

Что делает adr-code-traceability

Скилл помогает оставить в коде ссылку вида ADR: {adr-id}. Для нового файла, созданного при реализации ADR, он предлагает добавить её в заголовок; для нетривиального изменения существующего кода — добавить комментарий с причиной. Формат зависит от языка: описаны примеры для Python, TypeScript, Rust и Go.

Ссылки не нужны для каждой затронутой строки, форматирования и обычных идиом. Тесты тоже пропускаются, кроме случаев, когда подход к тестированию сам определён ADR. Идентификатор можно сопоставить с файлом по пути /docs/adr/{adr-id}.md; если в репозитории другой путь к ADR, стандартный пример нужно адаптировать.

Какие задачи решает

  • добавить ссылку на ADR в заголовок нового файла
  • объяснить нетривиальное решение комментарием в коде
  • выбрать место для ссылки на архитектурное решение
  • сократить лишние ссылки в изменённых строках

Примеры запросов агенту

  • Добавь ссылку на ADR в заголовок нового Python-файла для решения 2025-12-01-redis-session-cache.
  • Поясни комментарием в TypeScript, почему здесь выбрана эта реализация согласно ADR 2025-12-01-rate-limiting.
  • Проверь, где в этом изменении нужна ссылка на ADR, а где её добавлять не стоит.

Как установить adr-code-traceability

1Через Skills CLI (Vercel)

npx skills add terrylica/cc-skills --skill adr-code-traceability -a claude-code

2Вручную: положить файлы

~/.claude/skills/adr-code-traceability/SKILL.md

Папка скилла целиком; для одного проекта — .claude/skills/adr-code-traceability/

По шагам, с командами для каждой платформы: Как установить скилл в Claude Code: пять способов

Вопросы об adr-code-traceability

Как установить adr-code-traceability в Claude Code?

Выполните npx skills add terrylica/cc-skills --skill adr-code-traceability -a claude-code, затем используйте файл ~/.claude/skills/adr-code-traceability/SKILL.md.

Что делает adr-code-traceability?

Скилл помогает связывать код с архитектурными решениями: добавляет ссылку на ADR в заголовок нового файла или комментарий к нетривиальному изменению.

Для каких языков есть шаблоны ссылок на ADR?

В скилле приведены шаблоны для Python, TypeScript, Rust и Go. Для каждого языка показано, как оформить ссылку в заголовке или комментарии.

Исходный текст

SKILL.md · MIT
---
name: adr-code-traceability
description: Add ADR references to code for traceability. TRIGGERS - ADR traceability, code reference, document decision in code.
allowed-tools: Read, Edit, Grep, Glob
---

# ADR Code Traceability

Add Architecture Decision Record references to code for decision traceability. Provides language-specific patterns and placement guidelines.

> **Self-Evolving Skill**: This skill improves through use. If instructions are wrong, parameters drifted, or a workaround was needed — fix this file immediately, don't defer. Only update for real, reproducible issues.

## When to Use This Skill

- Creating new files as part of an ADR implementation
- Documenting non-obvious implementation choices
- User mentions "ADR traceability", "code reference", "document decision"
- Adding decision context to code during `/itp:go` Phase 1

## Quick Reference

### Reference Format

```
ADR: {adr-id}
```

**Path Derivation**: `ADR: 2025-12-01-my-feature` → `/docs/adr/2025-12-01-my-feature.md`

### Language Patterns (Summary)

| Language   | New File Header                      | Inline Comment              |
| ---------- | ------------------------------------ | --------------------------- |
| Python     | `"""...\n\nADR: {adr-id}\n"""`       | `# ADR: {adr-id} - reason`  |
| TypeScript | `/** ... \n * @see ADR: {adr-id} */` | `// ADR: {adr-id} - reason` |
| Rust       | `//! ...\n//! ADR: {adr-id}`         | `// ADR: {adr-id} - reason` |
| Go         | `// Package ... \n// ADR: {adr-id}`  | `// ADR: {adr-id} - reason` |

See [Language Patterns](./references/language-patterns.md) for complete examples.

---

## Placement Decision Tree

```
Is this a NEW file created by the ADR?
├── Yes → Add reference in file header
└── No → Is the change non-obvious?
    ├── Yes → Add inline comment with reason
    └── No → Skip ADR reference
```

See [Placement Guidelines](./references/placement-guidelines.md) for detailed guidance.

---

## Examples

### New File (Python)

```python
"""
Redis cache adapter for session management.

ADR: 2025-12-01-redis-session-cache
"""

class RedisSessionCache:
    ...
```

### Inline Comment (TypeScript)

```typescript
// ADR: 2025-12-01-rate-limiting - Using token bucket over sliding window
// for better burst handling in our use case
const rateLimiter = new TokenBucketLimiter({ rate: 100, burst: 20 });
```

---

## Do NOT Add References For

- Every line touched (only where traceability adds value)
- Trivial changes (formatting, typo fixes)
- Standard patterns (well-known idioms)
- Test files (unless test approach is an ADR decision)

---

## Reference Documentation

- [Language Patterns](./references/language-patterns.md) - Python, TS, Rust, Go patterns
- [Placement Guidelines](./references/placement-guidelines.md) - When and where to add

---

## Troubleshooting

| Issue                  | Cause                  | Solution                                  |
| ---------------------- | ---------------------- | ----------------------------------------- |
| ADR not found          | Wrong path format      | Use relative path from repo root          |
| Reference not showing  | Comment syntax wrong   | Check language-specific comment format    |
| Too many references    | Over-documenting       | Only add where traceability adds value    |
| Outdated ADR link      | ADR was renamed        | Update path to match current ADR filename |
| Hook reminder annoying | No ADR for this change | Add inline ADR comment or create new ADR  |


## Post-Execution Reflection

After this skill completes, check before closing:

1. **Did the command succeed?** — If not, fix the instruction or error table that caused the failure.
2. **Did parameters or output change?** — If the underlying tool's interface drifted, update Usage examples and Parameters table to match.
3. **Was a workaround needed?** — If you had to improvise (different flags, extra steps), update this SKILL.md so the next invocation doesn't need the same workaround.

Only update if the issue is real and reproducible — not speculative.

© terrylica · MIT · terrylica/cc-skills

Похожие скиллы

Каталог скиллов SKILL.md →
backward-traceability lingzhi227 Скилл backward-traceability связывает каждое число в научном PDF со строкой кода, которая его вычислила. Пригодится при оформлении статей в LaTeX для строгой проверки воспроизводимости данных. CX Codex +1 2 300установок adr-drafting giuseppe-trisciuoglio Скилл adr-drafting опрашивает разработчика об архитектурном решении, находит соглашения в репозитории и создаёт новый markdown-документ формата ADR. Пригодится при смене стека или разделении сервисов. CX Codex +1 3 700установок develop-adr product-on-purpose Скилл develop-adr для Claude Code оформляет архитектурное решение по формату Майкла Нигарда: фиксирует контекст, выбор и последствия. CX Codex +1 886установок adr-review ruvnet Скилл adr-review сверяет git-дифф с принятыми записями архитектурных решений (ADR). Помогает выявить нарушения архитектуры и устаревшие паттерны перед слиянием ветки. CX Codex +1 747установок adr-create ruvnet Скилл adr-create для Claude Code и пяти других платформ создаёт Architecture Decision Record с порядковым номером, регистрирует его в графе AgentDB и связывает с похожими решениями. Запускается на команду с названием решения. CX Codex +1 743установок 030-architecture-adr-general Juan Antonio Breña Moral Скилл 030-architecture-adr-general ведёт диалог с разработчиком и оформляет архитектурные решения (ADR) для Java-проектов в формате MADR. Помогает зафиксировать выбор базы данных или фреймворка. CX Codex +1 373установок

Из того же набора79

Весь набор →
plotext-financial-chart Скилл plotext-financial-chart строит текстовые финансовые графики в ASCII для Markdown-файлов через plotext. Помогает наглядно показать ценовые уровни прямо в документации на GitHub. CX Codex +1 146установок latex-setup Скилл latex-setup помогает установить и проверить LaTeX на macOS, настроить Skim и SyncTeX. Пригодится при подготовке новой машины или поиске проблем с пакетами. CX Codex +1 146установок adaptive-wfo-epoch Скилл adaptive-wfo-epoch подбирает число эпох обучения на каждом фолде walk-forward оптимизации и ранжирует кандидатов по walk-forward efficiency, а не по одному фиксированному значению. CX Codex +1 146установок log-reader Скилл log-reader читает логи MetaTrader 5 и вызовы Print() напрямую из файлов UTF-16LE без ручной проверки вкладки Experts в терминале. CX Codex +1 145установок mlflow-python Скилл mlflow-python для Claude Code записывает параметры и метрики бэктестов в MLflow. Ищет эксперименты и получает историю метрик через Python API. CX Codex +1 139установок code-clone-assistant Скилл code-clone-assistant находит повторяющийся код через PMD CPD и Semgrep, помогает рефакторить нарушения DRY. Работает с точными дубликатами и похожими паттернами. CX Codex +1 139установок article-extractor Скилл article-extractor выгружает статьи и документацию с mql5.com для датасетов или справочников. Помогает собирать примеры кода MQL5 по ссылкам и авторам. CX Codex +1 138установок glossary-management Скилл glossary-management для Claude Code ведёт глоссарий терминов и связывает его с Vale. Запускается при добавлении терминов, проверке формата или синхронизации словаря. CX Codex +1 138установок

Спонсоры проекта

Компании, которые помогают держать аналитику открытой