Markdown UI для ClaudeCode: как я построил локальный трекер задач для AI-агента

Вы запускаете ClaudeCode, ставите задачу, агент начинает работать — а через 20 минут контекстное окно заполняется, сессия закрывается, и всё, что агент помнил про прогресс задачи, испаряется. Знакомо?

Предыдущая система трекинга задач Todos имела критическое ограничение: элементы списка жили в памяти сессии и исчезали при её закрытии. Именно это разочарование толкнуло сообщество разработчиков на создание собственных локальных Markdown-интерфейсов для управления задачами AI-агента. В этой статье разберём, как устроены такие системы, почему Markdown — идеальный формат хранилища, и как собрать рабочий workflow своими руками.

Почему стандартные инструменты не работают с AI-агентом

ClaudeCode — это агентный инструмент для написания кода, который читает кодовую базу, редактирует файлы, выполняет команды и интегрируется с инструментами разработчика. Он доступен в терминале, IDE, десктопном приложении и браузере.

Но у агентного подхода есть особенность: ClaudeCode способен автономно работать над задачей примерно 10–20 минут, после чего эффективность падает по мере заполнения контекста.

Это означает, что для любого серьёзного проекта нужна внешняя персистентная память — место, где хранится состояние задач вне контекстного окна агента.

Многие разработчики сталкиваются с ограничениями контекстного окна и персистентности сессий, теряя прогресс между сессиями. Именно поэтому нужны механизмы трекинга зависимостей, параллельного выполнения подзадач и многосессионного сотрудничества.

Традиционные инструменты вроде Trello, Jira или Linear хороши для команд, но плохо вписываются в цикл «агент читает файл → агент пишет файл». Типичная проблема: задачи и заметки оказываются заперты внутри стороннего инструмента, а графический интерфейс создаёт лишнее трение.

Решение оказалось элегантно простым — локальные Markdown-файлы.

Архитектура локального Markdown-воркфлоу

Суть подхода описывается тремя принципами:

Храните спецификацию проекта в Markdown-файлах. В начале каждой сессии «гидрируйте» список задач из спецификации. По мере выполнения синхронизируйте прогресс обратно в файлы спецификации.

Типичная структура директорий выглядит так:

my-project/
├── CLAUDE.md              # Инструкции для агента
├── ROADMAP.md             # Общий роадмап проекта
├── .claude/
│   ├── session.md         # Текущий статус сессии
│   ├── commands/          # Slash-команды
│   └── agents/            # Специализированные агенты
└── tasks/
    ├── 001-auth.md        # Отдельная задача
    ├── 002-api.md
    └── today-2026-05-27.md  # Дневной список

CLAUDE.md — мозг системы

CLAUDE.md — это Markdown-файл, который вы добавляете в корень проекта. ClaudeCode читает его в начале каждой сессии. Используйте его для стандартов кодирования, архитектурных решений, предпочтительных библиотек и чеклистов проверки.

В project-specific claude.md-файле можно определить таксономию тегов, чтобы Claude автоматически и последовательно категоризировал новые задачи.

Отдельный файл на каждую задачу

Каждая задача — это отдельный Markdown-файл, хранящийся локально (например, в Obsidian vault). Это делает данные полностью переносимыми, доступными для поиска и понятными для Claude. Каждый файл задачи использует YAML front matter для структурирования метаданных.

Пример структуры файла задачи:

---
title: "Реализовать JWT-аутентификацию"
status: "in-progress"
priority: "high"
due: "2026-05-30"
tags: ["auth", "backend", "security"]
created: "2026-05-27"
---

## Описание
Добавить JWT-авторизацию для API endpoints.

## Шаги
- [ ] Установить зависимости
- [ ] Создать middleware
- [ ] Написать тесты
- [ ] Задокументировать

## Заметки агента
_Обновляется ClaudeCode автоматически_
💡 Совет по YAML
Добавьте поле agent_notes в YAML front matter. Агент будет записывать туда краткое состояние работы после каждого шага — это позволит быстро восстановить контекст в новой сессии без чтения всего файла.

Slash-команды: движок воркфлоу

Движок системы — это кастомная slash-команда в терминале. Команда /today запускает Python-скрипт. Задача скрипта — просканировать все файлы задач (хранящихся как Markdown) и сгенерировать новый Markdown-файл для текущего дня, включающий задачи на сегодня, просроченные элементы и идеи в работе.

Дневной файл, который генерирует /today, содержит несколько секций:

Задачи на сегодня — чеклист элементов с текущей датой выполнения; просроченные задачи — постоянный список всего незавершённого; идеи в работе — долгосрочные проекты для работы после завершения ежедневных задач; Research Digest — ссылка на автоматически найденные материалы по теме.

Адд задачи превращается в разговорный процесс:

Чтобы добавить задачу, просто введите инструкцию на естественном языке. Claude разберёт запрос, создаст новый Markdown-файл с корректными YAML-метаданными и добавит его в ваш ежедневный список дел.

Пример базового скрипта /today на Python:

#!/usr/bin/env python3
import os
import glob
from datetime import date
import yaml

def scan_tasks(tasks_dir="tasks/"):
    today = date.today().isoformat()
    due_today, overdue, in_progress = [], [], []

    for filepath in glob.glob(f"{tasks_dir}*.md"):
        with open(filepath) as f:
            content = f.read()
        # Простой парсинг YAML front matter
        if content.startswith("---"):
            _, fm, body = content.split("---", 2)
            meta = yaml.safe_load(fm)
            status = meta.get("status", "")
            due = meta.get("due", "")

            if status == "in-progress":
                in_progress.append((meta["title"], filepath))
            elif due == today:
                due_today.append((meta["title"], filepath))
            elif due and due < today and status != "done":
                overdue.append((meta["title"], filepath))

    return due_today, overdue, in_progress

def generate_today_file():
    today = date.today().isoformat()
    due_today, overdue, in_progress = scan_tasks()
    output = f"# Задачи на {today}\n\n"

    output += "## ✅ На сегодня\n"
    for title, path in due_today:
        output += f"- [ ] [{title}]({path})\n"

    output += "\n## 🔴 Просрочено\n"
    for title, path in overdue:
        output += f"- [ ] [{title}]({path})\n"

    output += "\n## 🔄 В работе\n"
    for title, path in in_progress:
        output += f"- [ ] [{title}]({path})\n"

    with open(f"tasks/today-{today}.md", "w") as f:
        f.write(output)
    print(f"Создан файл: tasks/today-{today}.md")

if __name__ == "__main__":
    generate_today_file()
ℹ Настройка shell-алиаса
Для работы slash-команды потребуется настроить shell-алиас или кастомный скрипт в конфигурационном файле терминала (.zshrc, .bash_profile и т.д.). Добавьте строку: alias today="python3 ~/scripts/today.py" — и команда будет доступна из любой директории.

State Machine: как заставить агента строго следовать процессу

Самая сложная часть — добиться от LLM детерминированного поведения. Простое описание процесса в текстовом виде не всегда работает.

Добиться того, чтобы Claude следовал воркфлоу, потребовало многих итераций и было близко к провалу несколько раз. Работа с одним лишь текстовым описанием не давала результата. Решением стал подход с конечным автоматом (state machine) — диаграмма в сочетании с письменной спецификацией состояний.

Вот как выглядит state machine для задачного воркфлоу:


graph TD
    A[Начало сессии] --> B[CHECK_STATUS]
    B --> C{Читаем .claude/session.md}
    C -->|Status = in-progress| D[WORKING]
    C -->|Status = Complete| E[AWAITING_COMMIT]
    C -->|Файл отсутствует| F[CREATE_PLAN]
    D --> G[Выполняем шаги задачи]
    G --> H[Обновляем session.md]
    H --> I{Задача завершена?}
    I -->|Нет| D
    I -->|Да| E
    E --> J[git commit]
    J --> K[Обновляем ROADMAP.md ✅]
    F --> L[Пишем план в task-файл]
    L --> D

Файл session.md — место, где Claude предоставляет краткие обновления по текущей задаче, чтобы при закрытии и перезапуске разговора можно было продолжить с того места, где остановились. Далее — конечный автомат, который указывает Claude, когда и почему трогать эти файлы, и принудительно задаёт ожидаемые поведения.

Пример содержимого .claude/session.md:

---
Status: in-progress
Task: tasks/002-api.md
Last Step: Создан базовый роутер, тесты написаны
Next Step: Добавить middleware авторизации
---
⚠ Важно
Опыт показывает: всякий раз, когда вы полагаетесь на LLM, следующий процессу, описанному в Markdown-файле — вы находитесь в уязвимом положении. Добавляйте явные маркеры состояния (🚨 FOLLOW EXACTLY) и заставляйте агента начинать каждое сообщение с текущего статуса — это позволяет быстро заметить отклонение от процесса.

Сравнение подходов к хранению состояния задач

За последний год сообщество выработало несколько паттернов. Вот сравнение ключевых:

ПодходПерсистентностьЧитаемость агентомЧитаемость человекомСложность настройки
todo.md / plan.md (монолит)✅ Да✅ Высокая✅ Высокая🟢 Низкая
Отдельный .md на задачу + YAML✅ Да✅ Высокая✅ Высокая🟡 Средняя
session.md + State Machine✅ Да✅ Очень высокая🟡 Средняя🔴 Высокая
JSON Tasks API (ClaudeCode v2.1+)✅ Да✅ Нативная🟡 Средняя🟢 Низкая
Внешний трекер (Jira/Linear)✅ Да🟡 Через MCP✅ Высокая🔴 Высокая

Лучший выбор — гибрид: YAML-файлы задач для человекочитаемой спецификации + session.md для машинного состояния агента.

Что появилось в ClaudeCode v2.1+

22 января 2026 года Anthropic выпустила ClaudeCode 2.1 с функцией, фундаментально меняющей работу с AI-ассистентом по написанию кода. Новая система Task management заменила ограниченную функциональность Todos полноценным слоем оркестрации, способным управлять сложными многосессионными проектами.

Task management в ClaudeCode значительно эволюционировал в v2.1.16 с введением Tasks API, дополняющего оригинальный инструмент TodoWrite. Этот воркфлоу учит, когда использовать каждую систему и как задействовать многосессионную координацию задач для сложных проектов.

Разделение планирования и исполнения: ключевой принцип

Один из важнейших инсайтов, который разработчики выявили на практике:

Ключевая идея — разделить планирование и исполнение.

На практике это выглядит так:

Фаза 1: Планирование (отдельная сессия с чистым контекстом)

Попросите агента написать подробный план в отдельных файлах задач внутри папки tasks. В ROADMAP.md добавьте инструкцию агенту — изучить существующую кодовую базу и понять текущее состояние, прежде чем составлять план. Это направляет агента на получение релевантного контекста до начала планирования.

Фаза 2: Проверка плана человеком

Проверьте сгенерированный план — на правильном ли он пути. При необходимости попросите агента внести правки. Как только вы удовлетворены планом, закройте текущую сессию или очистите контекст агента и начните новую сессию со свежим контекстом, чтобы получить максимальное контекстное окно для реальной реализации.

Фаза 3: Исполнение с контролем

При реализации: следуйте спецификациям в файле задачи, реализуйте функциональность, обновляйте прогресс по шагам в файле задачи после каждого шага, останавливайтесь после завершения каждого шага и ожидайте дальнейших инструкций.

📝 Пример команды для начала сессии
Прочитай .claude/session.md и ROADMAP.md.
Продолжи работу с задачи tasks/003-notifications.md.
После каждого шага обновляй session.md и останавливайся для подтверждения.

Такая инструкция гарантирует, что агент начнёт с нужного контекста, а не с нуля.

Nimbalyst и другие визуальные UI поверх ClaudeCode

Если CLI-подход кажется слишком суровым, существуют готовые решения с графическим интерфейсом.

Nimbalyst — это AI-native workspace, построенный поверх ClaudeCode — более широкий, чем традиционная Claude Code IDE. Наряду с полноценным редактором кода с inline AI diff review, он предоставляет визуальные редакторы для Markdown, макетов, диаграмм и data models, kanban-доску сессий, трекинг задач и мобильное приложение-компаньон.

Сессии организованы на канбан-доске по фазам — backlog, planning, implementing, complete. Весь рабочий поток виден с первого взгляда.

Ключевой принцип: вы должны владеть своими инструментами и файлами. Десктопное приложение, открытые форматы файлов, исходный код на GitHub.

Однако у готовых UI есть обратная сторона — они добавляют зависимость от третьего инструмента. Самодельный Markdown-воркфлоу работает в любом редакторе и не требует подписки.

Заключение: почему Markdown побеждает

Локальный Markdown-воркфлоу для ClaudeCode — это не хак и не временное решение. Это архитектурный выбор, продиктованный природой AI-агентов:

  • Персистентность: файлы переживают любую сессию и любой контекстный лимит
  • Портативность: данные не заперты в SaaS-инструменте
  • Читаемость: и человек, и агент работают с одним форматом
  • Версионность: файлы задач коммитятся вместе с кодом — история сохраняется
  • Расширяемость: можно добавить скрипты, MCP-интеграции, автоматические дайджесты

Это действительно интересно — у нас есть возможность проектировать кастомные воркфлоу для каждого проекта: как реализовывать задачи, как их валидировать. Вместо движения к жёстким spec-driven фреймворкам можно идти в обратную сторону и радикально проектировать собственный процесс под конкретный вид работы.

Начните с малого: создайте CLAUDE.md, добавьте папку tasks/, опишите первую задачу в YAML-файле. Уже через одну сессию вы почувствуете разницу между агентом, работающим «вслепую», и агентом с полным контекстом о том, что нужно сделать.