Codex Agent Core Template

Шаблон локального агента для Codex app.

Он помогает создать личного или рабочего AI-агента, который хранит знания не только в чате, а в обычных Markdown-файлах на вашем компьютере. Эти файлы можно читать руками, открывать в Obsidian, смотреть в графе связей и переносить между инструментами.

Главная идея: отделить постоянные правила агента от данных конкретного проекта.

Один Agent Core -> много Project Layers

Простыми словами

Agent Core — это “как агент работает”: правила, безопасность, порядок чтения файлов, согласование изменений, работа с источниками, records и проверками.

Project Layer — это “с чем агент работает”: организация, роль, исследование, личный проект, домен знаний, набор источников или другой контекст.

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

Кому это подходит

Этот template может быть полезен, если вы хотите:

• вести локальную базу знаний вместе с AI-агентом;
• не терять важные договорённости в длинных чатах;
• хранить знания в понятных файлах, а не только внутри модели;
• аккуратно разделять разные проекты и роли;
• смотреть структуру знаний в Obsidian;
• публиковать или переносить Agent Core без приватных проектных данных.

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

Основная связка v1

В первой версии template рассчитан на такую связку:

Codex app + локальные Markdown-файлы + Obsidian

• Codex app — основной AI-интерфейс и рабочий агент.
• Локальная папка — место, где живут правила, проекты, источники, записи и результаты.
• Obsidian — удобный просмотр файлов, навигация, граф связей и ручное чтение.

Obsidian не обязателен для работы агента, но полезен для понимания структуры.

Как это выглядит

flowchart LR
  U[Пользователь] --> C[Codex app]
  C --> A[Agent Core]
  A --> P[Project Layer]
  A --> F[Markdown-файлы]
  P --> F
  F --> O[Obsidian]

Loading

В Obsidian эта же папка выглядит как связанный граф Markdown-страниц:

Что внутри

• AGENTS.md — главные правила поведения агента.
• agent/ — Agent Core: модель работы, boot-протокол, правила изменений, источников, связей, lint, records и planning.
• .agents/skills/ — локальные procedural skills для Codex.
• projects/_template/ — шаблон project layer для ваших данных.
• raw/ — место для исходных материалов, которые нельзя редактировать напрямую.
• logs/ — журналы действий; рабочие logs обычно приватны и не публикуются.
• output/ — временные результаты и черновики.
• docs/ — документация по архитектуре, публикации и источникам идей.

Быстрый старт через Codex

Если у вас уже установлен Codex app, вам не обязательно заранее разбираться с Git.

1. Создайте на компьютере пустую папку для будущего агента.
2. Откройте эту папку в Codex app как рабочую папку проекта.
3. Напишите Codex в чате:

Скачай и разверни в эту папку шаблон локального агента из репозитория:
https://github.com/TheMuleA/codex-agent-core-template

Ничего не публикуй на GitHub.
Если нужен доступ к интернету, терминалу или изменение файлов, сначала объясни действие и спроси подтверждение.
После загрузки прочитай AGENTS.md. Ничего не меняй без подтверждения.

4. Codex предложит способ загрузки: через Git, если он доступен, или через ZIP-архив.
5. После загрузки начните новый чат в Codex фразой:

Читай AGENTS.md. Ничего не меняй без подтверждения.

6. Если реальный проект ещё не создан, агент задаст вопросы для первичного наполнения project layer.
7. После ваших ответов агент предложит создать projects/<project-id>/.
8. Файлы будут созданы или изменены только после вашего подтверждения.

Если Codex не может скачать репозиторий

1. Откройте страницу репозитория на GitHub.
2. Нажмите Code -> Download ZIP.
3. Распакуйте архив в отдельную папку на компьютере.
4. Откройте эту папку в Codex app.
5. Начните новый чат в Codex фразой:

Читай AGENTS.md. Ничего не меняй без подтверждения.

Что агент спросит при первом запуске

Если в папке есть только projects/_template/, агент не должен считать его рабочим проектом. Он задаст вопросы из projects/_template/onboarding-questions.md, например:

• как назвать project id;
• как называется проект;
• в какой роли должен работать агент;
• какая главная цель project layer;
• какие домены знаний нужны в первую очередь;
• какие источники считать доверенными;
• что точно вне scope;
• нужно ли сделать этот проект default.

После этого агент предложит структуру реального project layer.

Как агент меняет файлы

Агент не должен молча переписывать вашу базу знаний. Любое изменение проходит цикл:

CAPTURE -> CLASSIFY -> PROPOSE -> APPROVE -> APPLY -> LOG -> LINT

По смыслу это значит:

1. агент понял, что нужно сохранить или изменить;
2. определил тип изменения;
3. предложил конкретные файлы и текст;
4. дождался вашего подтверждения;
5. применил изменение;
6. записал, что было сделано;
7. проверил, что структура не сломалась.

Почему нельзя хранить всё в одном месте

Если смешать правила агента и данные проекта, со временем становится трудно понять:

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

Поэтому template разделяет:

• agent/ — постоянная агентская часть;
• projects/<project-id>/ — данные выбранного проекта;
• raw/ — исходники;
• logs/ — история действий;
• output/ — временные результаты.

Records

records/ — это не папка “для всего подряд”. Это место для коротких подтверждённых записей, которые важнее обычных заметок:

• facts;
• events;
• decisions;
• principles.

Новая запись сначала попадает в _inbox/, потом агент проверяет конфликты и предлагает promote. Promote выполняется только после подтверждения пользователя.

Можно ли использовать не только Codex

Сейчас template сделан в первую очередь под Codex app.

Потенциально эту архитектуру можно адаптировать под другие среды:

• Claude Code или похожие coding-agent интерфейсы;
• Antigravity и другие agentic IDE;
• AI-плагины внутри Obsidian;
• локально установленную модель;
• другой LLM-интерфейс, который умеет читать и менять локальные файлы.

Но v1 не требует этих инструментов. Базовая версия строится вокруг Codex, локальной папки и Obsidian как средства просмотра.

Безопасность и приватность

По умолчанию .gitignore защищает зоны, которые часто содержат приватные данные:

• project layers, кроме projects/_template/;
• raw sources;
• runtime logs;
• output;
• local archives;
• generated records;
• .obsidian/;
• .DS_Store.

Перед публикацией своего fork обязательно проверьте docs/publication-checklist.md.

Скриншоты

В README можно добавить скриншоты Obsidian: структуру папок, граф связей и пример первого boot-чата.

Пока изображения не добавлены, чтобы не оставлять битые ссылки. Рекомендации по изображениям лежат в docs/assets/README.md.

Источники идей

Архитектура вдохновлена LLM Wiki / second brain подходами, строгой процедурой skills и локальными Obsidian/Markdown knowledge systems.

Ссылки и credits:

• docs/reference-credits.md;
• agent/reference-sources.md.

Лицензия

Проект распространяется под лицензией MIT. См. LICENSE.