AutoMontage-Agent
AGENTS.md9 starsChanged 25 days agoMITView on GitHub
Каноническая инструкция для Claude Code и Codex. Читать перед любой работой в этой папке. Общие правила пользователя дополняют этот файл, но не заменяют его. AutoMontage-Agent – публичный MIT-движок локального автомонтажа видео. На входе – исходное видео и монтажный лист; на выходе – MP4 с Remotion-графикой, субтитрами, b-roll, музыкой и финишной обработкой через ffmpeg. Транскрибация выполняется локально через faster-whisper. Главные документы: - README.md – установка и использование; - docs/MONTAGE-GUIDE.md – простой путь от исходного видео до проверенного final MP4; - docs/reels-guide/…
- Reads credentials
In this repository15 other files it gives its agents.
- CLAUDE.mdCLAUDE.md
- ai-promoSkill
- motion-reelSkill
- reel-from-donorSkill
- reel-turnkeySkill
- ai-promoSkill
- lead-magnetSkill
- motion-reelSkill
- reel-from-donorSkill
- reel-turnkeySkill
- ai-promoSkill
- lead-magnetSkill
- motion-reelSkill
- reel-from-donorSkill
- reel-turnkeySkill
The file
Files
AutoMontage-Agent – правила проекта
Каноническая инструкция для Claude Code и Codex. Читать перед любой работой в этой папке. Общие правила пользователя дополняют этот файл, но не заменяют его.
Что это за проект
AutoMontage-Agent – публичный MIT-движок локального автомонтажа видео. На входе – исходное видео и монтажный лист; на выходе – MP4 с Remotion-графикой, субтитрами, b-roll, музыкой и финишной обработкой через ffmpeg. Транскрибация выполняется локально через faster-whisper.
Главные документы:
README.md– установка и использование;docs/MONTAGE-GUIDE.md– простой путь от исходного видео до проверенного final MP4;docs/reels-guide/– курс для новичка «Ролики с нуля»: от идеи и текста до публикации, аватар или своя съёмка, пульт, лид-магнит к ролику и готовые фразы для агента;docs/TAKES.md– монтаж одного ролика из нескольких дублей или записей простым языком;docs/REVIEW-WORKBENCH.md– полный пользовательский путь монтажа в браузере;docs/SCENE-CATALOG.md– семь официальных сцен и их допустимые варианты;ARCHITECTURE.md– устройство и потоки данных;docs/TEMPLATES.md– доступные композиции и обязательный lesson-процесс;docs/MOTION-KIT.md– motion-слой ролика из готовых деталей движка и его автоматические проверки;TESTING.md– уровни проверки;DECISIONS.md– принятые решения и их причины;CHANGELOG.md– история релизов и заметные изменения по версиям;ROADMAP.md– стратегические направления продукта, без списка задач;CONTRIBUTING.md– как завести задачу, выбрать приоритет и вести её по доске.
HANDOFF.md, PLAN.md, docs/STEP-*, docs/PHASE4-adaptive.md, docs/UPGRADES.md
и датированные implementation plan – архивные снимки. Они сохраняют историю, но не являются
источником текущих команд и поведения.
Старт каждой сессии
- Прочитать этот файл и
MEMORY.md, если локальная память существует. - Прочитать последний файл в
memory/и_progress.md, если они существуют. - Выполнить
git status --short,git log -10 --onelineи проверить текущую ветку. - Не перезаписывать пользовательские исходники, рендеры и незакоммиченные изменения.
- Под задачу читать только нужный документ: архитектуру, тестирование или конкретный файл из
knowledge/. - Выполнить
automontage inbox. Если в пульте есть правки или утверждения, одной строкой сообщить о них пользователю и начать с них, если пользователь не назвал другую задачу. Если среди утверждений есть строки с пометкой «в архиве», в этой же фразе упомяни, что они есть, но не начинай их без отдельной просьбы пользователя. - Перед крупной работой найти её Issue по правилам раздела «Задачи и приоритеты».
Локальных файлов памяти нет в свежем клоне – это нормально, агент не должен из-за этого останавливаться.
Задачи и приоритеты
Будущая работа живёт в GitHub, а не в чате и не в дневнике. Четыре источника правды:
| Вопрос | Источник |
| Что конкретно исправить или внедрить? | Issues |
| Что важнее и на каком этапе работа? | Project «Product Backlog»: поля «Статус», «Приоритет», «Область» |
| Куда продукт движется крупными этапами? | ROADMAP.md |
| Почему возникла проблема и как устроено решение? | локальный knowledge/<тема>.md; в Issue – вывод без личных путей |
memory/ – дневник уже сделанного, а не пятый список задач. Обязательные правила:
- перед крупной подзадачей найти соответствующую Issue; если её нет – проверить дубликаты
и создать карточку через форму (
.github/ISSUE_TEMPLATE/); - найденный системный баг, идею или техдолг не оставлять только в чате: записать в Issue;
- статусы доски: Входящие → Бэклог → Готово к работе → В работе → Проверка → Выпущено;
приоритет P0–P3 ставить по влиянию, а не по эмоции (значения – в
CONTRIBUTING.md); - перед словом «готово» обновить Issue (что сделано, как проверено) и статус на доске;
- закрывать Issue только после выпуска и проверки результата, не в момент написания кода;
- не переносить в GitHub секреты, персональные данные, клиентские видео и личные пути.
Клиентский монтаж конкретного ролика ведётся в пульте и projects/<id>/, а не в Issues;
в Issue попадает только общий дефект или возможность движка.
Пульт роликов
automontage pult – главный экран пользователя со всеми роликами из projects/. Пульт только
показывает состояние и записывает решения; монтаж и правки делает агент. Единственное
исключение – финал из просмотренного preview (DECISIONS.md D-051): после «Утверждаю» пульт
копирует проверенный по sha256 чистый полный preview в финал, без рендера.
- Утверждение в пульте вызывает ту же
approveBrief, что и Review, поэтому равносильно явному «утверждаю» для этой версии brief и preview. Полный 1080p preview рендерится в качестве финала (без CRF 28 и без вшитого «ЧЕРНОВИК» – надпись рисует плеер), поэтому утверждение в пульте, Review или черезscripts/project/approve-brief.jsобычно сразу даёт финал копированием: карточка «Готов», строки «Утверждено» нет, final QA идёт в фоне. Строка «Утверждено» вautomontage inboxостаётся, только когда preview продвинуть нельзя (фрагмент, 4K, preview до D-051, устаревший preview, сбой копирования), и означает: собери final рендером и проведи полный QA. Еслиapprove-brief.jsнапечаталfinal: …, рендер не нужен. - Строка «Проверка финала…» во входящих – фоновый final QA финала из preview. «Идёт» – жди.
«Есть предупреждения» – прочитай отчёт
qa/final-*.txt, исправь при необходимости новой ревизией, затемautomontage inbox --ack-final-qa <папка>. «Пройдена» – просто отметь тем же флагом. «Не выполнена» – запустиautomontage qa-final projects/<папка>и отметь. - После финала и его QA (рендер, финал из preview после «Пройдена» в «Проверка финала…») агент
ВСЕГДА предлагает чистку этого ролика:
automontage clean --project <папка> --level archiveбез--yes– показать пользователю ГБ и список файлов, удалять командой с--yesтолько после явного «да» пользователя в чате. Строка «Можно освободить N ГБ: …», которую печатают сборка финала иapprove-brief.js, – подсказка с размером, а не разрешение. Никогда не удаляй файлы без «да»; финал, текущее ТЗ, слой текущего ТЗ и исходники чистка не трогает. - Нажатие «Утверждаю» в пульте на архивной карточке само возвращает её из архива: само утверждение и есть просьба пользователя собрать финал. Поэтому такое утверждение приходит во входящих обычной строкой «Утверждено: …» без пометки «в архиве» – собирай final и проводи QA как обычно.
- Строка «Утверждено» с пометкой «в архиве – не начинай без просьбы пользователя» появляется, когда карточка утверждена, но лежит в архиве, а именно: её убрали в архив уже ПОСЛЕ утверждения (обратный порядок действий); утверждение прошло не через кнопку «Утверждаю» в пульте (Review Workbench, явное «утверждаю» в чате) – такое утверждение пульт не возвращает из архива сам; или сам возврат из архива не удался (внутренняя ошибка пульта). Явное «утверждаю» в текущем чате уже и есть просьба – собирай финал в этом же чате; пометка важна для следующих сессий, где такой явной просьбы в диалоге уже не видно. В новом чате без отдельной просьбы не начинай собирать по такой карточке финал сам; просто держи её в поле зрения до отдельной просьбы. Убрать такую строку без финала можно только решением пользователя «финал не нужен» (правило ниже), а не по своему усмотрению. Просьба – сообщение пользователя, где назван этот ролик или его папка (в том числе фраза «Продолжи ролик …», скопированная из пульта); после возврата карточки из архива пометка исчезает сама. На новые правки архив не влияет – выполняй их как обычно; новый preview такого ролика пользователь найдёт во вкладке «Архив».
- Утверждение в пульте – решение пользователя, а не агента: никогда не вызывай API пульта
(
/api/approve) и не утверждай ролик от имени пользователя. Основание для final – только «Утверждаю» в пульте, нажатое пользователем, или его явное «утверждаю» в чате. - «Финал не нужен» – тоже решение пользователя, как и утверждение: никогда не вызывай API пульта
(
/api/final-declined) сам.automontage inbox --decline-final <папка>– только по явным словам пользователя в чате, что финал этого ролика не нужен;--restore-final <папка>– так же, только по его словам. Версия с таким решением не появляется во входящих; новое утверждение того же ролика (новый brief) снова приносит строку «Утверждено». Новые правки к ролику выполняй как обычно. - Правки из пульта привязаны к секунде и кадру. Выполни их новой draft-ревизией и новым полным
preview (правки к черновой нарезке – по правилам ниже), затем отметь каждую:
automontage inbox --accept <папка> <id>, где<папка>– имя папки без префиксаprojects/(во входящих путь показан какprojects/<папка>). - Черновая нарезка (
automontage roughcut,skills/reel-turnkey/references/rough-cut.md) – сокращение записи без графики, которое автор смотрит до master и слоя. Правки к ней без подтверждения выполняй новой нарезкойedit/roughcut-v(NN+1).jsonи снова жди автора. Строка «Нарезка подтверждена» вautomontage inboxозначает: автор подтвердил нарезку – внеси правки к ней, собери master и переходи к слою.edit/roughcut-vNN.jsonпосле подтверждения не меняй: скопируй его вedit/vNN-source.json(тот жеsourceRevision), внеси вырезы по секундам исходника изautomontage inbox, собери master из этой копии и отметь правкиautomontage inbox --accept. Без правок master собирается прямо изedit/roughcut-vNN.json. - Подтверждение нарезки – решение автора, а не агента: никогда не вызывай
/api/roughcut/confirmи не нажимай «Нарезка готова» за автора.automontage roughcut confirm– только по явным словам автора в чате («нарезка готова», «нарезка ок»). Фраза «режь сам» после показа нарезки – тоже явное подтверждение: выполниautomontage roughcut confirmи продолжай. Та же фраза до показа снимает этап: нарезку не показывай. - Строки «Лид-магнит: …» во входящих выполняй по навыку
skills/lead-magnet/SKILL.md. Утверждает лид-магнит только человек в пульте; команды утверждения у агента нет. - Каждый новый ролик создаётся с паспортом
project.json(--project,automontage motion --project). Варианты одной темы (оригинал и хуки, ролики серии) получают в своих папкахpult-card.jsonс общимgroup, например{"version":1,"group":{"id":"tema-slug","title":"Тема"},"variantLabel":"Хук 1"}. - Папке без
project.json, где лежат готовые видео, заводиpult-card.jsonс блокомlegacy(status,variants[].label,variants[].video). Схема –schema/pult-card.schema.json. - Если
automontage inboxпишет «Паспорт ролика не читается» или «Файл правок повреждён», сначала починиproject.jsonилиpult/comments.jsonэтой папки, затем выполняй правки.
Обязательная карточка «Что делаем?» в новом чате
Когда пользователь в новом чате передаёт видео или просит «смонтировать ролик», до технической работы покажи одну компактную карточку «Что делаем?» – до четырёх вопросов по 2–4 варианта (в Claude Code – AskUserQuestion, в Codex – follow-up actions или Markdown-блок):
- «Что делаем?»: Ролик со смыслом (рилс, пост, обзор) · Рекламный промо под музыку · Урок или длинное видео · Лид-магнит.
- «Формат?»: Вертикаль 9:16 (Reels, Shorts, Stories) · Горизонталь 16:9 (YouTube, пост).
- «Из чего собираем?»: Моя запись с камеры · Камера и экран (запись OBS) · Без съёмки – тема, текст или музыка · По ссылке-референсу.
- «Как монтируем?»: Уникальный Creative Motion – рекомендуется · Creative Motion + оверлеи
Higgsfield (тратит кредиты: смета и «да» до генерации) · Готовый стиль (только реально
доступные публичные темы и приватные
THEMES_EXT) · Решай сам (= Creative Motion).
Не спрашивай то, что уже ясно из запроса или файлов: файл 16:9 отвечает на формат, ссылка – на «по референсу», названный маршрут – на «Как монтируем?». Если ясно всё, карточку не показывай. Вопроса о длительности нет: длину агент выбирает сам (промо – 20–30 с) и называет её в плане. «Реши сам» и «на твоё усмотрение» означают Creative Motion.
Коротко о маршрутах: Ролик со смыслом со своей записью и Урок – reel-turnkey (lesson, формат
исходника); без съёмки – motion-reel (--aspect horizontal для 16:9); промо под музыку –
ai-promo (--music-only); по ссылке – reel-from-donor (только вертикаль 9:16); Лид-магнит –
lead-magnet. Камера и экран: автоматической синхронизации двух файлов нет, экран идёт
broll-врезками поверх записи с камеры. Полная таблица – в creative-motion.md.
Карточка – одна точка решения. После ответа работай автономно: не перекладывай на пользователя
шрифт, цвет, музыку, переходы, тайминги или технические решения; покажи всё одним полным
preview. Обязательные пользовательские точки – три: один выбор маршрута в начале, подтверждение
черновой нарезки (для своей съёмки с речью; у аватара и после «режь сам» его нет) и явное
утверждение просмотренного preview перед final.
После final и QA агент всегда предлагает чистку этого ролика
(automontage clean --project <папка> --level archive: ГБ и список файлов) и удаляет только
после явного «да» пользователя в чате – это вопрос о диске, а не четвёртая точка монтажа.
Полный контракт выбора, автономности, уникального дизайна и QA находится в
skills/reel-turnkey/references/creative-motion.md, числа и запреты движения – в
skills/reel-turnkey/references/motion-craft.md, порядок черновой нарезки – в
skills/reel-turnkey/references/rough-cut.md. Навыки reel-turnkey, reel-from-donor и
motion-reel обязаны применять их в своих маршрутах.
Неподвижные правила продукта
- Формат lesson-ролика по умолчанию равен пропорциям и FPS исходника; рабочее разрешение –
1080p по короткой стороне (
automontage master), 4K – только явным--quality source. Вертикаль или горизонталь задаются только явным--aspect. - Lesson проходит через жёсткий гейт: транскрипция → смысловая раскладка → проруф →
Markdown + JSON со статусом
draft→ явное утверждение →approved→ рендер. - Draft, другой исходник, другая тема или другой аспект не должны попадать в Remotion.
- Для своей съёмки с речью тайминги фиксирует автор до слоя и до brief: черновая нарезка → «Нарезка
готова» → master из оригинала. Пока нарезка ждёт автора,
masterиlayer newотказывают. У аватара нарезки нет: master из своего спискаedit/v02-source.json. Оговорка, найденная после master, режется новым master и новым слоем – это полный круг. - В стандартном маршруте автоматический режиссёр lesson выбирает только из 7 официальных сцен:
fullscreen,split,bottom-diagram,blur-overlay,text-only,stat,broll.chartэкспериментален и в автоматический план не входит. Creative Motion не добавляет клиентские типы сцен в общий движок: он подключает нормализованный project-local motion-слой через поддерживаемуюbroll/media-сцену. - В готовом стиле агент заполняет существующие сцены фактами и дословными формулировками из
речи. В Creative Motion он создаёт новый арт-дирекшн и неповторяющиеся композиции внутри
projects/<id>/, сохраняя общий approval, safe-zone, global-timecode и QA-контракт. - Приватный бренд-пак подключается через
THEMES_EXTи не копируется в этот репозиторий. - Аудио и каждый видеослой сцены используют глобальный таймкод исходника. Нельзя
обнулять видео на каждой новой
Sequence. - B-roll в draft может содержать
brollIntentбез файла: цель и исходная фраза из речи, исходный и английский запросы. Сохраняй такую сцену с[ B-ROLL ]заглушкой в preview, не заменяй её наsplitтолько из-за отсутствия файла. Поиск и ранжирование автоматические, выбор материала выполняет человек в Review; только выбранный полный файл импортируется. - Discovery-материал сохраняется как проверенный локальный asset с SHA-256 и provenance. Незаполненный intent и неподтверждённый OCR warning блокируют approval. Для discovery нужен актуальный полный Remotion-preview и явное подтверждение просмотра; поиск, выбор, импорт, Save и завершение preview никогда не утверждают brief и не запускают final render.
- Ролик без речи (музыкальное промо) идёт через
automontage motion <саундтрек> --project <имя> --music-only: Whisper не запускается, brief получаетaudioRole: "music", а preview, явное утверждение и final – те же, что у обычного motion-reel. Маршрут – навыкskills/ai-promo/SKILL.md; в карточке «Что делаем?» это ответ «Рекламный промо под музыку».
Политика AI и API-ключей
- Основной способ работы AutoMontage-Agent - через текущую подписку Claude Code или Codex.
- Для расшифровки, анализа речи, подготовки lesson-ТЗ, выбора сцен, Review, утверждения и рендера отдельные API-ключи не нужны.
- Агент должен самостоятельно прочитать локальный транскрипт, создать валидные Markdown- и JSON-файлы lesson-brief, проверить их и продолжить монтаж.
- Запрещено запрашивать
ANTHROPIC_API_KEYдля монтажа или подготовки ТЗ. - Запрещено запрашивать
OPENAI_API_KEYдля монтажа, транскрибации, подготовки ТЗ, Review или рендера. OPENAI_API_KEYразрешён только если пользователь явно запросил генерацию изображений через OpenAI, а используемая в текущем монтаже модель сама не умеет генерировать изображения.- Даже при выполнении этого условия ключ можно использовать только для явно запрошенной генерации изображений через OpenAI и нельзя применять для каких-либо других задач.
- Наличие ключа в окружении не считается разрешением на платный API-вызов.
- Перед генерацией изображений агент обязан предупредить, что будет использован отдельный платный API, и получить явное подтверждение пользователя.
- Если пользователь не подтвердил такой вызов или используемая модель умеет генерировать
изображения самостоятельно,
OPENAI_API_KEYиспользовать нельзя. - Если старый скрипт требует API для lesson-ТЗ, агент не должен просить ключ. Он должен использовать локальный транскрипт и подготовить brief самостоятельно в текущей сессии.
- Видео, Whisper, Review, Remotion и FFmpeg должны работать локально.
PEXELS_API_KEYнеобязателен и нужен только для бесплатного интернет-поиска stock B-roll через официальный Pexels API. Без него основной монтаж и ручной импорт остаются рабочими. Ключ читается локально; не передавай его браузеру, в логи или ошибки. Remotion вызывается через общий resolver с отдельным публичным env-файлом, чтобы корневой.envне попал в браузер рендера. Подробности:docs/REVIEW-WORKBENCH.md.- Никогда не просить пользователя отправлять ключ в чат.
- Higgsfield – платный сервис кредитов тарифа пользователя, подключается как OAuth MCP
(
mcp__higgsfield) без API-ключа: токен живёт во входе Claude Code. Никогда не запрашивай, не храни, не логируй и не коммить токены, не клади их в.envили Issues. - Подключённый MCP не считается разрешением тратить кредиты. Сначала
get_costна каждую задачу, затем смета. Генерация – только после явного «да» пользователя на конкретную смету: либо на одну партию, либо один раз на весь план с разбивкой по партиям (модели, число вариантов, кредиты каждой партии, общий потолок). Всё сверх утверждённой сметы – лишние варианты, повторы, новая партия, ценаget_costвыше сметы – требует нового вопроса. Названный пользователем потолок без сметы – не согласие. Автоматических повторов нет, обход модерации запрещён. - Внешность реального человека – только с его согласия и по референсам из его собственной
съёмки, которые лежат в
projects/<id>/. Порядок работы –skills/ai-promo/SKILL.md.
Структура
scripts/ CLI, оркестрация пайплайна, ffmpeg/Python-утилиты
scripts/lesson/ aspect, валидация brief и draft/approved workflow
scripts/review/ локальный Review API, импорт медиа и безопасные команды правок
scripts/pult/ сервер, каталог, inbox и CLI «Пульта роликов»
review/ browser-интерфейс Review Workbench без собственного renderer
pult/ браузерный интерфейс пульта
src/ Remotion-композиции, блоки, темы и режиссёр сцен
src/scenes/ семь сцен lesson, общие части и safe-zone
schema/ JSON Schema монтажного листа и lesson brief
tests/ unit- и регрессионные тесты Node test runner
public/ шрифты и публичные демо-ресурсы; личные исходники игнорируются
props/ готовые props/монтажные листы для рендера
examples/ маленькие воспроизводимые демо
docs/ шаблоны, правила монтажа, планы и инструкции этапов
out/, tmp/ локальные артефакты; в Git не попадаютПолная карта и связи модулей – в ARCHITECTURE.md.
Команды
npm ci # воспроизводимая установка Node-зависимостей
npm test # все unit- и регрессионные тесты
npm run doctor # проверка Node, Python и ffmpeg
npm run demo # лёгкий тестовый рендер без ключей и Whisper
npm run review -- --project-dir <путь> # локальная проверка lesson-проекта
node scripts/cli.js --help # актуальные пользовательские флаги
automontage pult # «Пульт роликов» со всеми роликами
automontage inbox # правки и утверждения из пульта для агента
automontage roughcut --project-dir <p> --edit edit/roughcut-v01.json # черновая нарезка для автора
automontage roughcut confirm --project-dir <p> # «нарезка готова» – только по словам автора
automontage queue # состояние очереди тяжёлых задач
automontage clean # отчёт, что можно удалить у готовых роликов; --yes удаляет
automontage clean --project <папка> --level archive # один ролик сразу после финала; --yes только после «да»Боевые команды и проверки lesson-процесса описаны в docs/TEMPLATES.md и TESTING.md,
а работа в браузерном окне - в docs/REVIEW-WORKBENCH.md.
Разработка
- Node.js 20+; CommonJS в
scripts/и тестах, React/JSX вsrc/. - Python нужен только для локальной транскрибации, анализа лица, reframe и генераторов.
- Новое поведение сначала закрыть тестом. Для исправления бага нужен регрессионный тест, который воспроизводит его причину.
- Тайминг Remotion считать от FPS композиции, не от фиксированного числа кадров.
- Пользовательский текст и цифры не выдумывать: только транскрипт и утверждённое ТЗ.
- Прежде чем делать полный рендер, валидировать JSON и проверять несколько контрольных кадров.
- Не добавлять реальные видео, музыку, токены, абсолютные личные пути и приватные темы.
Client-delivery mode
Во время монтажа конкретного клиентского ролика изменять можно только его игнорируемую папку
projects/<id>/. Не править src/, scripts/, schema/, общие тесты, публичную документацию
или тему ради одной версии ролика. Draft разрешено визуально проверять только настоящей командой
automontage preview; финальные renders/ и final/ остаются approved-only (финал из preview
появляется только после утверждения человеком). Если нужной общей
возможности нет, использовать ближайший поддержанный вариант и вынести изменение движка в
отдельную задачу. В Creative Motion разрешены локальные React/Remotion-компоненты,
design tokens и сцены внутри projects/<id>/motion-vNN/: они рендерятся в полноразмерный слой,
официально нормализуются и подключаются к brief без изменения общего движка.
Security testing
При закрытии уязвимости обязательно добавить regression test в tests/ с payload,
который воспроизводил проблему, и соседний positive-case для легитимного ввода.
Запуск: npm test.
🔴 Документация – держать в синхроне
После каждого изменения кода обновляй документацию в том же подходе. Если код и описание расходятся, источником истины является проверенное поведение кода, а документ нужно исправить.
| Что изменилось | Что обновить |
| Пользовательская команда или флаг | README.md, при необходимости docs/TEMPLATES.md |
| Модуль, композиция или порядок пайплайна | ARCHITECTURE.md |
| Переменная окружения | .env.example, README.md |
| Формат scenario/brief | соответствующая схема в schema/, ARCHITECTURE.md, тесты |
| Заметное поведение или исправление | CHANGELOG.md |
| Выпуск версии | package.json, package-lock.json, CHANGELOG.md, версия в README.md |
| Архитектурный выбор с альтернативами | DECISIONS.md |
| Команда или критерий проверки | TESTING.md, CI при необходимости |
Motion-kit, команды automontage layer или гейты G1–G12 | docs/MOTION-KIT.md |
| Крупное направление продукта или процесс ведения задач | ROADMAP.md, CONTRIBUTING.md |
Перед завершением задачи спросить себя: «Сможет ли следующая сессия понять текущее состояние только по коду, Git и этим документам?»
Версии следуют SemVer. Новые совместимые возможности повышают minor, исправления – patch,
несовместимые изменения – major. До релиза записи накапливаются в [Unreleased]; релиз
получает секцию X.Y.Z с датой и Git-тег vX.Y.Z.
Память проекта
Память локальная, потому что репозиторий публичный:
MEMORY.md– постоянные факты и решения, лимит 200 строк;memory/YYYY-MM-DD.md– хронология сессий и следующие шаги;memory/feedback_<тема>.md– устойчивые корректировки пользователя;knowledge/– причины сложных багов, чек-листы и накопленные уроки;_progress.md– временный трекер только для большой незавершённой задачи.
Полный регламент – instructions/memory-rules.md. Эти файлы перечислены в
.gitignore: они доступны следующим сессиям на этом Mac, но не публикуют личные пути,
исходники и рабочий контекст на GitHub.
Git и публичность
В Git идут общие документы (AGENTS.md, README.md, ARCHITECTURE.md,
TESTING.md, DECISIONS.md, CHANGELOG.md, ROADMAP.md, CONTRIBUTING.md, .env.example),
формы задач и CI. В Git не идут
локальная память, _progress.md, .env*, исходные ролики, музыка, рендеры и приватный
бренд-пак.
Перед коммитом проверить git diff --cached, затем запустить privacy-check и Gitleaks.
node scripts/check-public-privacy.js --staged читает точные bytes Git index и блокирует
клиентские артефакты, личные пути, локальную память, .env и медиа без записи в ASSETS.md;
Gitleaks отдельно ищет ключи и токены. Локальный hook .githooks/pre-commit запускает обе
проверки; GitHub CI проверяет публичное дерево и повторно сканирует полную историю на push и PR.
Hook активируется командой git config core.hooksPath .githooks. Не обходить его через
--no-verify. Push и публикация – только по явному запросу.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

