adr-code-traceability — скилл для Claude Code: ссылки на ADR в коде
Скилл adr-code-traceability для Claude Code добавляет ссылки на Architecture Decision Records в заголовки новых файлов и комментарии к нетривиальным решениям. Связывает код с архитектурным решением.
MIT 144 установок ★ 3 обновлён 2026-10-25
npx skills add terrylica/cc-skills --skill adr-code-traceability -a claude-codeЧто делает 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-code2Вручную: положить файлы
~/.claude/skills/adr-code-traceability/SKILL.mdПапка скилла целиком; для одного проекта — .claude/skills/adr-code-traceability/
1Через Skills CLI (Vercel)
npx skills add terrylica/cc-skills --skill adr-code-traceability -a codex2Вручную: положить файлы
.agents/skills/adr-code-traceability/SKILL.mdДля всех проектов — ~/.agents/skills/
1Через Skills CLI (Vercel)
npx skills add terrylica/cc-skills --skill adr-code-traceability -a cursor2Вручную: положить файлы
.cursor/skills/adr-code-traceability/SKILL.mdCursor читает и .agents/skills/, и .claude/skills/
1GitHub CLI
gh skill install terrylica/cc-skills plugins/itp/skills/adr-code-traceability2Вручную: положить файлы
.github/skills/adr-code-traceability/SKILL.md1Через Skills CLI (Vercel)
npx skills add terrylica/cc-skills --skill adr-code-traceability -a gemini-cli2Командой платформы
gemini skills install https://github.com/terrylica/cc-skills --path plugins/itp/skills/adr-code-traceabilityВручную: положить файлы
.devin/skills/adr-code-traceability/SKILL.mdСтарый путь .windsurf/skills/ тоже читается
Через Skills CLI (Vercel)
npx skills add terrylica/cc-skills --skill adr-code-traceability -a opencodeClaude.ai
Упакуйте папку в zip и загрузите в Settings → Capabilities → Skills
По шагам, с командами для каждой платформы: Как установить скилл в 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