Maximus — агентная инженерная система обучения

Maximus — локальная evidence-first система инженерного обучения. Она связывает граф компетенций, учебные циклы, лабораторные, ревью, экзамены, англоязычные интервью, сигналы рынка и read-only поиск open-source задач в один адаптивный процесс. Maximus предлагает, измеряет и проверяет; ученик выполняет работу, подтверждает результат и принимает решения сам.

Быстрый старт

Требуется Go 1.24 или новее.

make verify
make build
./bin/maximus version
./bin/maximus init --profile learner --name "Learner"
./bin/maximus baseline --profile learner
./bin/maximus plan --profile learner --start 2026-08-03 --weeks 6 --hours 25
./bin/maximus next --profile learner --at 2026-08-03
./bin/maximus profile --profile learner

Все успешные workflow-команды возвращают JSON; только version печатает текстовый идентификатор сборки. Ошибка выводится в stderr и завершает процесс с ненулевым кодом.

Приватность и границы

Единственный источник истины — SQLite. По умолчанию база находится в .local/maximus.db; путь можно заменить глобальным --db. Профиль, исходные тексты CV и вакансий, локальные пути, ответы, оценки, evidence и история планов приватны. Импорт отклоняет распространённые credential patterns до записи, а CLI и MCP не возвращают тело импортированного источника или его локальный путь.

Evidence становится доступным публичному экспорту только после явного public; значение по умолчанию — private. Портфолио и LinkedIn-текст строятся через public-only границу, остаются локальными и не отправляются в GitHub, LinkedIn или иной сервис. Maximus не публикует, не подаёт заявки, не пишет рекрутерам и не выполняет действия за ученика.

Требование evidence-before-completion обеспечивает агентский workflow Maximus: authoritative policy в .agents/AGENTS.md и role skills разрешает роли завершать plan item только после принятого evidence. Низкоуровневые typed интерфейсы complete-plan-item в CLI и complete_plan_item в MCP сейчас доверяют переданному вызывающей стороной completion metadata и сами не проверяют наличие отдельной evidence row. Поэтому прямой caller обязан соблюдать эту policy самостоятельно; успешный ответ raw CLI/MCP не доказывает, что evidence был прикреплён.

Путь ученика: 9 возможностей

Каждый сценарий ниже отвечает на четыре вопроса: что получится, с чего начать, какие данные останутся в системе и что всё равно должен сделать человек.

1. Профиль и приватный импорт

• Результат: локальный профиль с фиксированным стартовым значением weekly_hours = 25 и приватная база источников — CV, вакансий, описаний интервью и исследований — с digest, provenance и временем проверки.
• Старт: ./bin/maximus init --profile learner --name "Learner", затем source-import или import-vacancy; в агентском режиме — onboarding, а для разбора источника — market-analyst.
• Данные: имя профиля, фиксированный default 25 часов, исходное тело источника, метаданные и hash хранятся в SQLite локально; тело и путь не выходят через CLI/MCP.
• Действие человека / предел: ученик выбирает файл, подтверждает его происхождение и задаёт часы отдельно для каждого плана через plan --hours. Интерфейса обновления доступности в профиле сейчас нет. Maximus не читает приватные аккаунты и не импортирует данные без явного локального пути.

2. Базовая оценка и карта мастерства

• Результат: завершённая baseline-сессия, evidence-backed rubric scorecard и производная карта mastery по компетенциям.
• Старт: ./bin/maximus baseline --profile learner; продолжение выполняется командами assessment-next, assessment-submit, assessment-scorecard и assessment-complete, либо ролью examiner.
• Данные: сессия, каждый ответ, версии blueprint/rubric, оценки и события mastery остаются приватными в SQLite; незавершённые ответы не объявляются достижением.
• Действие человека / предел: ученик отвечает сам, по одному вопросу. Экзаменатор не даёт подсказок, а итог требует полного scorecard с цитируемым evidence; Maximus не может честно оценить отсутствующий ответ.

3. Адаптивное планирование

• Результат: утверждённый шестинедельный план с точными часами, prerequisites, проверками и одним следующим действием; каждые две недели его можно пересобрать по фактическому evidence.
• Старт: ./bin/maximus plan --profile learner --start 2026-08-03 --weeks 6 --hours 25 и ./bin/maximus next --profile learner; для proposal/approval/replan — одноимённые CLI-команды или роль planner.
• Данные: версии плана, выбранные для конкретного cycle weekly_hours, входные параметры, причины изменений, approvals, элементы и immutable completion events хранятся локально. Минимальный бюджет — 25 часов: 4 theory, 7 lab, 7 project, 4 open source, 2 assessment, 1 review.
• Действие человека / предел: ученик выбирает plan --hours для каждого generated cycle и явно утверждает proposal. Это значение не обновляет фиксированные 25 часов в profile: availability-update interface пока нет. Рыночный сигнал меняет приоритет, но не обходит prerequisites и не создаёт mastery без evidence.

4. Обучение и лабораторные

• Результат: одна изученная тема или лабораторная с артефактом, фактическим выводом verification-команды и принятым evidence, после чего role workflow может завершить соответствующий plan item.
• Старт: ./bin/maximus next --profile learner; дальше выбрать роль tutor для объяснения или lab для эксперимента. Роли работают через typed MCP tools get_next_task, attach_evidence и complete_plan_item.
• Данные: прикреплённые через role workflow URI/описание evidence, выбранная видимость, immutable learning event и производный mastery snapshot остаются в SQLite; private — значение по умолчанию. Raw completion metadata само по себе не является independently verified evidence row.
• Действие человека / предел: ученик пишет код, запускает команду и показывает попытку. Агентская role policy требует evidence до completion, но direct CLI/MCP caller должен обеспечить эту последовательность сам. До попытки роль не раскрывает решение; Maximus не придумывает результат запуска и не редактирует лабораторную за ученика.

5. Ревью и экзамены

• Результат: bounded review конкретного diff/ADR/benchmark с приоритетными замечаниями, очередь spaced reviews и строгая topic assessment без подсказок.
• Старт: роль reviewer после появления попытки; очередь — ./bin/maximus review-queue --profile learner --at 2026-08-10T09:00:00Z; экзамен — assessment-start --profile learner --blueprint ID или examiner.
• Данные: learner-owned artifacts и verification evidence приватны; review events, следующая дата повторения, ответы, rubric scores и mastery сохраняются локально.
• Действие человека / предел: ученик исправляет замечания, принимает остаточный риск и отвечает на экзамене сам. Reviewer не реализует fix, а examiner не даёт hints и не завершает assessment без полного evidence.

6. Англоязычные интервью

• Результат: hard staff-level simulation на английском и полный evidence-backed отчёт по rubric dimensions; после сессии разбор обучения может быть на русском.
• Старт: ./bin/maximus interview --profile learner, затем assessment commands, либо роль interviewer.
• Данные: prompts идентифицируются blueprint/item ID, а ответы, scorecard, оценки и дата завершения хранятся приватно; скрытые rubric/solutions не раскрываются кандидату.
• Действие человека / предел: кандидат отвечает на английском, по одному вопросу. Maximus не даёт leading follow-ups, не имитирует решение работодателя и не заявляет о найме.

7. Рынок и open source

• Результат: подтверждённое отображение рыночного требования на competency, явно одобренный приоритет, ranked shortlist из primary/backup OSS issue и локально отслеживаемый contribution lifecycle.
• Старт: source-import, market-map, market-priority-approve или роль market-analyst; для OSS — oss-search, oss-classify, oss-shortlist-approve, oss-select и роли oss-scout/oss-mentor.
• Данные: рыночные source bodies и mappings приватны. Публичные issue metadata, classification, contributor-guidance evidence, approvals, выбранная задача и learner-evidenced lifecycle сохраняются локально.
• Действие человека / предел: ученик одобряет mapping/shortlist, сам создаёт branch/PR, пишет комментарии и общается с maintainer. GitHub discovery только read-only; Maximus не мутирует сеть и не выдаёт внешний milestone без learner-owned evidence.

8. Портфолио и публичный прогресс

• Результат: детерминированные English drafts для progress Markdown и LinkedIn, построенные только из явно публичных доказательств.
• Старт: ./bin/maximus export --profile learner или роль portfolio-editor через create_public_progress.
• Данные: генератор читает public-only mastery/evidence и возвращает drafts локально; private source body, private evidence и локальные пути в результат не попадают.
• Действие человека / предел: ученик проверяет утверждения, сохраняет нужный текст и публикует его сам. Maximus не добавляет неподтверждённые claims и не вызывает publishing API.

9. Обслуживание и восстановление

• Результат: диагностика окружения и целостности, консистентный backup, проверенный restore и атомарная пересборка derived projections из immutable истории.
• Старт: ./bin/maximus doctor, verify, audit, backup --to FILE, restore --from FILE и rebuild --profile learner; для read-only проверки прогресса — роль progress-auditor.
• Данные: backup содержит всю приватную SQLite-базу и требует такой же защиты. Rebuild не переписывает историю, а восстанавливает mastery, review schedules и OSS lifecycle projections.
• Действие человека / предел: владелец выбирает защищённый путь backup, закрывает конфликтующие процессы перед restore и устраняет findings аудита. Maximus не может подтвердить внешний human review или восстановить данные, которых нет в ledger/backup.

CLI: полный каталог

Глобальные options ставятся перед командой:

./bin/maximus --db /absolute/path/maximus.db doctor
./bin/maximus --content-root /absolute/path/to/checkout doctor

Authored content выбирается в порядке: явный --content-root, затем MAXIMUS_CONTENT_ROOT, затем embedded defaults. Development root должен быть родителем полного content/; невалидный явный или environment override завершает запуск с ошибкой. Опциональный live network check для doctor включается через MAXIMUS_NETWORK_CHECK=1.

Command	Назначение
init --profile ID [--name NAME]	Создать профиль и идемпотентно загрузить competency seed.
source-import --kind KIND --path FILE --provenance TEXT [...]	Приватно импортировать content-addressed CV, vacancy, interview process или research.
import-vacancy --path FILE --company NAME --role TITLE	Импортировать локальную вакансию как dated market source.
market-map ... / market-priority-approve ...	Предложить validated requirement mapping и записать явное approval.
baseline --profile ID / interview --profile ID	Запустить authored baseline или hard staff interview.
assessment-start, assessment-next, assessment-submit	Вести generic baseline/exam/interview с одним immutable ответом за шаг.
assessment-scorecard, assessment-complete	Получить scorer-safe rubric и атомарно записать полный evidence-backed результат.
plan --profile ID --start DATE [--weeks 6] [--hours 25]	Создать и утвердить начальный deterministic plan revision.
plan-propose, plan-approve, plan-replan	Предложить, явно утвердить или пересмотреть план после evidence review.
next --profile ID [--at DATE]	Вернуть следующий scheduled task.
complete-plan-item --profile ID --item ID --at TIME [--metadata JSON]	Добавить immutable completion с caller-provided metadata; raw command сам не проверяет evidence row.
review-record / review-queue	Записать competency review и получить due queue.
profile --profile ID	Получить приватный профиль и derived mastery.
oss-search, oss-classify, oss-shortlist-approve	Read-only найти issue, записать classification и утвердить shortlist.
oss-select, oss-deselect, oss-lifecycle	Связать approved issue с планом и вести learner-owned lifecycle.
export --profile ID	Создать локальные public-only progress и LinkedIn drafts.
doctor / verify / audit	Проверить prerequisites, окружение, graph, privacy и integrity invariants.
backup --to FILE / restore --from FILE	Создать или восстановить validated SQLite snapshot.
rebuild --profile ID	Атомарно пересобрать event-derived projections.
mcp	Запустить stdio MCP server.

MCP: типизированный агентский доступ

Сначала соберите бинарник, затем укажите абсолютный путь в MCP client:

{
  "mcpServers": {
    "maximus": {
      "command": "/absolute/path/to/maximus/bin/maximus",
      "args": ["mcp"]
    }
  }
}

Server identity — maximus. MCP предоставляет только typed domain tools для profile, imports/mappings, plans, assessments, evidence, reviews, projection rebuild, read-only OSS discovery, local OSS decisions/lifecycle и public drafts. record_interview_score остаётся compatibility alias для complete_assessment. Универсального SQL tool, publishing tool и unrestricted network mutation нет.

12 агентских ролей

Перед ролью прочитайте .agents/AGENTS.md: там закреплена identity «Максимум», общие language/privacy/evidence rules и точный список разрешённых MCP tools. Каждая роль наследует identity, но не получает дополнительных permissions.

Role	Что делает	Жёсткая граница
onboarding	Создаёт или возобновляет профиль, объясняет следующий шаг.	Не придумывает достижения; один вопрос за раз.
planner	Выбирает работу на шесть недель и один следующий task.	Изменение плана требует evidence и явного approval.
tutor	Объясняет тему по-русски и принимает проверяемую практику.	Не записывает progress без artifact/command output.
lab	Ведёт один learner-owned эксперимент.	До попытки не даёт hint/solution; не подделывает запуск.
reviewer	Проверяет один diff, ADR, benchmark или explanation.	Не реализует fix и не ослабляет evidence contract.
examiner	Проводит baseline/topic exam без подсказок.	Не раскрывает hidden rubric/solution.
interviewer	Проводит hard staff interview на английском.	Не даёт hints и не заявляет hiring outcome.
oss-scout	Read-only ранжирует подходящие public issues.	Не создаёт issue/comment/branch/PR.
oss-mentor	Ревьюит learner-owned OSS attempt.	Не действует в community за ученика.
market-analyst	Приватно mapping-ит требования рынка.	Не публикует source и требует approval для priority.
progress-auditor	Read-only проверяет evidence, gaps и readiness.	Не мутирует ledger или plan.
portfolio-editor	Делает English drafts из public-only evidence.	Не читает private evidence и не публикует.

Объяснение, teaching, feedback и plans — на русском. Interview questions и candidate answers — на английском. Code, shell commands, official source titles, GitHub queries, PR/comments, portfolio/LinkedIn drafts и любое community-facing содержимое — на английском. Все роли задают не более одного вопроса за раз и останавливаются на своём explicit stop condition.

Архитектура и authored content

• content/ — version-controlled competency graph, восемь adaptive strategic cycles, six-week curriculum, baseline и hard interview blueprints.
• internal/app/ — единый application facade для CLI и MCP.
• internal/store/ — embedded migrations, immutable learning ledger, evidence, plans, assessments и projections.
• internal/ops/ — doctor, audit, SQLite-consistent backup/restore и replay.
• internal/mcpserver/ — strict typed domain tools без SQL.
• .agents/ — authoritative identity, routing и role-specific workflows.

Authored JSON встроен в бинарник через go:embed, поэтому абсолютный путь к бинарнику работает из любого current directory. Lifecycle locking базы поддерживается на macOS и Linux; другие OS компилируются с явной unsupported platform ошибкой вместо запуска без корректного cross-process lock.

Каждый learning unit обязан содержать две-три HTTPS-ссылки, evidence requirements и verification command. Двенадцатимесячная карта задаёт направление, а не календарное обещание: переход разрешён только после принятого exit evidence, а следующий six-week plan меняется по mastery, reviews, market signals и реальным ограничениям ученика.

Backup, restore и schema recovery

./bin/maximus backup --to "$HOME/maximus-2026-07-25.db"
./bin/maximus restore --from "$HOME/maximus-2026-07-25.db"
./bin/maximus verify
./bin/maximus rebuild --profile learner

Restore сначала проверяет SQLite integrity и migrations, затем под exclusive adjacent DB_PATH.lock атомарно заменяет target. Перед pending migrations существующая база получает private, fsynced snapshot вида maximus.db.pre-upgrade-v023-to-v024.db. Если upgrade частично завершился и упал, startup закрывает SQLite, восстанавливает исходную базу из snapshot и возвращает путь и результат recovery. Новая пустая база не создаёт бессмысленный pre-upgrade snapshot.

Разработка и проверка

make verify
make build
./bin/maximus --db /tmp/maximus-check.db verify

make verify запускает race tests, go vet, content checks и validation всех 12 repo-local skills без обязательной сети. При изменении поведения сначала добавьте focused failing test; не добавляйте private learner data, secrets или скопированный live issue content в repository.

Отложенные web и voice интерфейсы

Текущий MVP — local-first CLI + stdio MCP. В нём намеренно нет web UI, account sync, browser automation, voice listener, speech synthesis и автоматической публикации. Будущий web/voice interview UI может использовать тот же typed MCP facade и SQLite privacy boundary, но сейчас это roadmap, а не доступная возможность. Реальный project review, maintainer feedback, employer interview и другие human milestones остаются внешним evidence: Maximus может записать предоставленное доказательство, но не может связаться с человеком или автоматически подтвердить, что событие произошло.