devlog

name	devlog
description	Зафиксировать значимое изменение в .claude/devlog/ после завершения фичи, багфикса, рефакторинга, изменения конфига/CLI/API, добавления тестов или принятия архитектурного решения. Создаёт entries/NNNN-slug.md с YAML frontmatter и регенерирует index.json. Trigger on: '/devlog', 'запиши в devlog', 'обнови changelog', 'зафиксируй изменения', а также автоматически после значимых правок кода.
argument-hint	[краткое описание изменения, опционально]
allowed-tools	Read, Write, Bash(devlog-reindex:*), Bash(python3:*), Bash(ls:*), Bash(test:*), Bash(git diff:*), Bash(git log:*), Bash(git status:*)

Навык: ведение devlog

Добавляет запись в <project>/.claude/devlog/entries/ после значимых изменений. Источник правды — markdown с frontmatter; index.json + tldr.md генерируются скриптом и не редактируются вручную.

Скрипт регенерации поставляется внутри этого плагина и доступен как команда devlog-reindex на PATH, пока плагин включён (обёртка в bin/ находит skills/devlog/rebuild-index.py относительно себя — ${CLAUDE_PLUGIN_ROOT} в Bash-окружении не экспортируется, поэтому опираемся на PATH, а не на путь). Команда принимает devlog root через CLI-аргумент / $CLAUDE_PROJECT_DIR / cwd-relative fallback. Проекту достаточно создать .claude/devlog/entries/ — копировать что-либо в проект не нужно. Исключение — teammate/CI без этого плагина должны регенерировать индекс сами: тогда положи копию rebuild-index.py в <project>/.claude/devlog/rebuild-index.py, зови в README локальный путь, и при наличии project-копии используй её (она — pin проекта).

SessionStart-дайджест (тоже поставляется этим плагином). Хук hooks/session-start-digest.sh в начале каждой сессии поднимает в контекст последние 3 devlog-записи и до 3 активных progress-файлов (.claude/progress/*.md, кроме помеченных CLOSED). В проектах без .claude/devlog/ и .claude/progress/ хук молчит (exit 0 без вывода); read-only, без сети; git-статус не дублирует — его Claude Code инжектит сам. Это автоматизация session-start-ритуала harness-кита: state-on-disk сам находит следующую сессию, записи не нужно искать вручную.

Когда использовать

• После завершения фичи, исправления бага, рефакторинга
• После изменения конфигурации, API-контракта, CLI-интерфейса, auth flow
• После принятия архитектурного решения
• Когда пользователь явно просит зафиксировать изменения

НЕ использовать для:

• Опечаток, форматирования, комментариев
• Промежуточных состояний (незавершённые изменения)
• Чтения кода, research, ответов без правок

Алгоритм

1. Bootstrap devlog в проекте (один раз)

Если .claude/devlog/entries/ не существует — создай:

mkdir -p .claude/devlog/entries

2. Определи scope изменений

Используй один из вариантов:

• Незакоммиченные: git diff --name-only + git diff --staged --name-only
• В feature branch: git diff main...HEAD --name-only
• На main: git diff HEAD~1 --name-only
• Если пользователь указал конкретные изменения — используй их.

3. Определи следующий id

ls .claude/devlog/entries/ 2>/dev/null | grep -E '^[0-9]{4}-' | sort | tail -1

Возьми число из имени последнего файла + 1. Zero-pad до 4 цифр (0001, 0002, ..., 0017). Если каталог пуст — начни с 0001.

4. Сформулируй title и slug

• title — короткий заголовок (< 80 символов), глагол в прошедшем времени + что сделано. Пример: «Добавлена фильтрация по ключевым словам».

• slug — детерминированно из title через slugify():

  1. lowercase
  2. кириллица → латиница (транслитерация: ж→zh, х→kh, ц→ts, ч→ch, ш→sh, щ→shch, ю→yu, я→ya, ъ/ь → пусто, остальные посимвольно)
  3. все символы кроме [a-z0-9] → -
  4. сжать множественные - в один
  5. trim - по краям
  6. обрезать до 60 символов, trim хвостовой -

  Пример выше → dobavlena-filtratsiya-po-klyuchevym-slovam. Файлы, созданные до транслитерации (кириллица просто выбрасывалась), валидны — rebuild-index.py принимает оба варианта slug'а.

Имя файла: NNNN-{slug}.md. Если ошибся — devlog-reindex подскажет правильное имя в ошибке.

5. Создай entry-файл

Путь: .claude/devlog/entries/NNNN-slug.md.

Язык записи — рабочий язык пользователя (RU/EN/любой): заголовки секций и текст пиши на нём. Шаблон ниже показан по-русски, но ## Context / ## Changes / … равноправны. rebuild-index.py берёт preview из первой ## -секции независимо от языка заголовка, поэтому ## Контекст и ## Context работают одинаково; slug при этом всегда латинизируется (шаг 4).

---
id: <NNNN без zero-pad, как int>
date: <YYYY-MM-DD>
title: "<title>"
tags: [<тип>, <область>]
status: complete
---

# <title>

## Контекст
Какая проблема решалась или какая цель достигается. **Первый параграф** —
самодостаточное one-paragraph объяснение мотивации (≤280 символов
идеально); `rebuild-index.py` вытащит его в `preview` (в `index.json`
и `tldr.md`) как plain-текст: разметка снимается, ссылки схлопываются
в свой текст — href живёт только здесь, в entry. Дальше — детали,
2-4 предложения.

## Изменения
Что конкретно сделано. Ключевые решения и trade-offs. Code blocks где уместно.

## Затронутые файлы
- `path/to/file.py` — что изменилось

## Проверка
Команды, тесты, ручная проверка.

## Related
- #<id> — кратко о связи (если есть связанные записи)

Tags — комбинация типа и области:

Тип	Когда
feature	Новая функциональность
bugfix	Исправление бага
refactor	Реструктуризация без изменения поведения
config	Изменение конфига, env vars, auth flow
docs	Значимые изменения документации
security	Уязвимость, улучшение безопасности
test	Добавление/изменение тестов
cleanup	Удаление мёртвого кода
adr	Архитектурное решение (контекст / motivation / consequences / alternatives)

Область — свободная (например: api, db, frontend, cli, prompts, harness).

6. Регенерируй derived артефакты

devlog-reindex

Команда автоматически найдёт devlog root по cwd (./.claude/devlog/), либо через $CLAUDE_PROJECT_DIR/.claude/devlog/. Также принимает явный путь как первый аргумент: devlog-reindex /path/to/project/.claude/devlog.

Если сразу после установки плагина devlog-reindex не находится (command not found) — плагин ещё не подгрузил свой bin/ в PATH: выполни /reload-plugins или перезапусти сессию. Требуется Python 3 на PATH (только stdlib); при его отсутствии обёртка выдаст явную ошибку.

• exit 0 + index.json + tldr.md updated: N entries (devlog root: ...) — успех
• exit 1 + ошибки в stderr — исправь и запусти снова. Типичные ошибки:
  • required field 'X' missing — добавь поле в frontmatter
  • frontmatter id N != filename id M — переименуй файл или поправь id
  • filename slug 'X' != slugify(title)='Y' — переименуй файл в NNNN-Y.md
  • duplicate id N — два файла с одним id, исправь нумерацию
  • devlog root not found — запусти из корня проекта или передай путь аргументом

7. Отчёт пользователю

Devlog обновлён: #<id> — <title>
Tags: <tags> | Файл: entries/NNNN-slug.md
Index: <N> записей

Иммутабельность

Если изменение отменяет или заменяет существующую запись — НЕ редактируй старую. Создай новую с supersedes: <id_старой> в frontmatter. В body новой записи объясни, что именно изменилось и почему.

Допустимы только технические правки старых записей: опечатки, битые ссылки, несоответствие формата.