Как навести порядок в проектах с помощью GitHub: простая система без дублирования

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

В результате непонятно, чему верить. Один документ говорит, что функция уже опубликована, другой — что это только проверенная сборка. В одном репозитории лежит своя «главная» спецификация, хотя реальный контракт принадлежит соседнему проекту. А агент получает несколько похожих команд и вынужден угадывать, какая из них важнее.

Эта тема продолжает предыдущий разбор: «GPT опять запутался и сделал всё не так?» — о том, как пересекающиеся и устаревшие инструкции создают ошибки ещё до начала работы.

Надёжнее сделать не «больше документации», а яснее распределить ответственность между несколькими файлами в GitHub.

Главный принцип: у каждого типа знания один владелец

В системе полезно разделить не документы, а вопросы, на которые они отвечают.

• Где находится проект и какая спецификация ему принадлежит?
• Что подтверждено сейчас и что делать дальше?
• Какие требования нельзя менять без решения?
• Какие действия допустимы для агента прямо в этом репозитории?
• Что уже происходило раньше?

Если на каждый вопрос отвечает один источник, дублирование исчезает само. Остальные документы не копируют ответ, а ссылаются на владельца.

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

Пять файлов вместо одного «универсального документа»

Минимальная схема состоит из пяти ролей.

Реестр

PROJECTS.json

ID проекта, репозиторий, основная ветка и владелец спецификации.

Локальный указатель

.project-system.json

Только ID проекта и адрес центральной памяти.

Карточка проекта

projects/<id>/CARD.md

Подтверждённый статус, следующий шаг и ссылки на решения.

Мастер-спецификация

MASTER-SPEC.md

Подробный продуктовый и технический контракт.

Операционные правила

AGENTS.md

Короткие safety-правила и границы действий агента.

История проверок, попыток выпуска и старых решений не должна раздувать мастер-спецификацию. Её место — в журнале activity с датой и ссылкой на evidence.

Такое разделение даёт простой ответ на типичный вопрос: «сборка прошла — это уже релиз?» Нет. Сборка, CI, deploy, live-проверка и принятие пользователем — разные факты. Текущий подтверждённый факт попадает в карточку проекта, а не превращается в вечную фразу внутри технического контракта.

Минимальный указатель внутри каждого репозитория

Локальный файл не должен повторять реестр. Если и PROJECTS.json, и .project-system.json содержат название репозитория, ветку и путь к master spec, они однажды разъедутся.

Поэтому локальному репозиторию достаточно знать свой стабильный ID и путь к памяти:

{
  "schema_version": 3,
  "project_id": "blog",
  "memory": {
    "repository": "your-org/MemoryGPT",
    "path": "projects/blog"
  }
}

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

Почему AGENTS.md должен быть коротким

AGENTS.md особенно легко превратить в второй MASTER-SPEC. Туда попадают описание архитектуры, последовательности публикации, история тестов, правила внешних сервисов и даже старые решения. Потом мастер-спецификация обновляется, а инструкция — нет.

Короткий AGENTS.md лучше оставляет только то, что помогает не совершить опасное действие именно сейчас:

• не отправлять сообщение или не деплоить без явного подтверждения;
• не раскрывать секреты, персональные данные и закрытые ссылки;
• не заменять утверждённый медиафайл «похожим» вариантом;
• не считать локальный тест доказательством production;
• не обходить границы read-only интеграции.

Подробное объяснение этих правил остаётся в MASTER-SPEC. Повторять в AGENTS допустимо только критический стоп-сигнал, который предотвращает необратимое действие.

Cross-repo спецификация: не создавайте копии

Иногда один проект использует продуктовый контракт другого. Например, отдельный контентный репозиторий может зависеть от спецификации основного сайта, а прототип — от общей спецификации продукта.

В таком случае важно не создавать «облегчённую копию» MASTER-SPEC в зависимом репозитории. Единственный владелец должен быть указан в реестре. Локальный AGENTS.md может коротко сказать: «читай спецификацию владельца read-only; изменяй её только в его репозитории».

Это устраняет тихий конфликт версий: больше не нужно сравнивать две похожие master specs и решать, какая из них «свежее».

Внешние сервисы не должны управлять проектом

Таблицы, заметки, чаты и другие внешние сервисы могут быть удобным представлением данных или рабочим инструментом команды. Но они не должны становиться вторым центром управления.

Внешний сервис может хранить вспомогательные материалы или быть источником данных конкретного продукта, но не определяет:

• какой репозиторий является проектом;
• где лежит текущая спецификация;
• какой статус считать подтверждённым;
• что должен делать агент.

Эти ответы остаются в GitHub и проходят обычную проверку через историю изменений.

Настройки GPT: как не создать вторую спецификацию

Настройки GPT полезны для устойчивого стиля работы, но они не заменяют проектную документацию. В ChatGPT персональные инструкции настраиваются через Settings → Personalization → Custom Instructions и применяются ко всем чатам; их можно изменить или отключить позднее. Официальная справка OpenAI описывает этот механизм и его границы.

В персональные инструкции стоит выносить только долговременные предпочтения:

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

Не стоит помещать туда названия репозиториев, текущие статусы, ветки, пути к файлам, токены, пароли и подробные процессы выпуска. Такие сведения быстро устаревают, различаются между проектами или чувствительны. Им место в GitHub: в реестре, карточке проекта, MASTER-SPEC или локальном AGENTS.md.

Хорошая проверка проста: если настройка должна быть одинаковой почти во всех будущих чатах, она подходит для GPT. Если она относится к одному проекту, конкретной версии или текущему релизу, её нужно хранить в проекте.

Проверки, которые не дают системе снова засориться

Один раз навести порядок недостаточно. Нужна простая автоматическая или ручная проверка перед принятием migration:

• у каждого ID есть одна запись в реестре и одна карточка;
• локальный pointer содержит только разрешённые минимальные поля;
• путь к зарегистрированной MASTER-SPEC существует;
• в governance-файлах нет локальных путей вроде /Users/...;
• в AGENTS.md нет копии общего workflow и маршрутизации через внешний сервис;
• относительные ссылки на ключевые документы разрешаются;
• safety, publication, deploy и privacy-правила не ослаблены при сокращении текста.

Это не бюрократия ради бюрократии. Такая проверка ловит самые дорогие ошибки: битые ссылки, ложные production-claims и ситуацию, когда важное правило случайно исчезло во время «чистки документации».

Короткое руководство: как применить GitHub-модель в своём проекте

1. Создайте центральный репозиторий памяти и добавьте в него PROJECTS.json.
2. Для каждого проекта заведите стабильный project_id, карточку projects/<id>/CARD.md и один зарегистрированный MASTER-SPEC.
3. Добавьте в рабочий репозиторий минимальный .project-system.json с ID и адресом центральной памяти.
4. Сократите AGENTS.md: оставьте только правила, которые защищают от опасных действий в этом репозитории.
5. Перенесите текущий статус и next action в карточку, а дату, результаты проверок и старые попытки — в activity.
6. Если спецификация принадлежит другому репозиторию, укажите владельца только в реестре и не создавайте копию.
7. Проверьте все маршруты, ссылки и safety-инварианты до того, как удалить старые документы.
8. Отдельно фиксируйте build, CI, deploy и live-проверку: один успешный этап не доказывает остальные.

После этого GitHub перестаёт быть просто местом для кода. Он становится прозрачной картой проекта: видно, где принимать решения, что уже доказано и какое действие действительно следующее.

Готовый промпт для агента

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