Как 1ADK разбирает систему, к которой у него нет доступа?

#Два пути

Они отличаются тем, кто переносит описание. Они не отличаются ни тем, что пересекает границу, ни тем, кто решает, что останется.

У каждого проекта есть страница подключения, и она спрашивает, как вы хотите работать. Claude Code и Codex подключаются вставленным в них блоком текста — Codex вдобавок требует одной строки, которую вы выполняете в своей оболочке сами. Работа вручную — третий ответ в том же ряду, а не сноска под двумя другими, и он остаётся в ряду после того, как машина подключена: кто-то не станет подключать к репозиторию ничего, и эта позиция не стоит ему продукта.

#Подключение привычного агента

Блок текста, который вставляют в Claude Code или Codex, — а для Codex ещё одна строка, которую вы выполняете сами. Никакой программы 1ADK ставить не нужно.

1. Вы открываете страницу подключения и выбираете агента

   Страница спрашивает, как вы хотите работать, и предлагает три ответа рядом: Claude Code, Codex или вручную. Выберите один из первых двух — и 1ADK покажет блок текста.

   Адрес репозитория не спрашивают ни там, ни когда проект заводится. Поля для него просто нет.

2. Вы вставляете этот блок в агента

   Вставляйте его в агента, уже открытого в той папке, где лежит код: именно это решает, какой проект будет подключён. Это набор указаний, написанных для агента, а не команда, которую нужно понимать вам: агент забирает одноразовый код, годный несколько минут, добавляет 1ADK в свой собственный список инструментов, проверяет, что это работает, и обычными словами говорит вам, получилось или нет.

   Самого ключа в блоке нет никогда: в тот момент, когда блок написан, ключа ещё не существует. Codex требует одной лишней строки, которую вы выполняете сами, потому что берёт постоянный ключ только из переменной окружения; эта строка живёт ровно столько, сколько открыт тот терминал, и 1ADK даёт вторую — чтобы это работало в любом терминале.

3. Вы просите анализ, когда он вам нужен

   На странице подключения видно, что подключено, и там же есть кнопка Scan now — кабинет 1ADK на английском. 1ADK открывает задание; подключённая машина сама его спрашивает, читает систему там, где она уже лежит, и отправляет описание обратно.

   Машина отвечает тому, кто её подключил, поэтому Scan now принадлежит ему; остальные участники проекта запускают анализ вручную, и он покрывает ровно то же самое. 1ADK никогда не обращается к этой машине — любой обмен начинается с вашей стороны.

4. Вы решаете, что будет записано

   Пришедшее описание проходит проверку и остаётся ждать. Вы видите сводку: сколько компонентов, сколько открытых вопросов, что агент не смог установить, — и решаете, становится ли это знанием проекта.

   Подключение не делает ничего автоматическим. Этот шаг одинаков на обоих путях.

#Вручную

Ничего не подключено, ничего не настроено, и продукт работает.

Ручной режим существует потому, что возражение за ним законное. Если ваш ответ на вопрос «может ли инструмент держать ключ, который дотягивается до машины с этим репозиторием?» — нет, этот ответ не должен стоить вам анализа. Агента просят искать то же самое, и результат тот же. Отличается одно правило, и ровно ради него этот путь и выбирают: ручная инструкция запрещает агенту открывать сетевые соединения вообще и велит остановиться на файле на диске.

1. Скопировать инструкцию

   На странице задания лежит блок текста. Его копирует в кодовый агент — Claude Code, Codex или любой другой, умеющий читать локальный репозиторий, — тот, у кого код уже выгружен.

   Инструкция статична и работает только на чтение: она запрещает что-либо менять, запускать приложение, гонять миграции и тесты и открывать сетевые соединения.

2. Прочитать файл и загрузить его

   Агент пишет один JSON-файл в корень вашего репозитория и останавливается. Никуда ничего не отправляется. Кто-то открывает файл, видит ровно то, что там написано про его систему, и загружает в 1ADK, если его это устраивает.

   Это единственный путь, на котором человек может прочитать каждый байт до того, как он уйдёт с машины. Ради этого он и предложен.

3. Вы решаете, что будет записано

   1ADK проверяет файл и держит его — ровно так же, как держит описание, пришедшее по подключению. Пока человек с вашей стороны не одобрил конкретный файл, в хранилище проекта не попадает ничего.

#Что пересекает границу

Самое важное предложение про 1ADK — отрицательное, и в нём стоит быть точным. На обоих путях оно одно и то же.

#Что лежит в описании

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

Показывать его стоит не ради схемы. Смысл в том, что единица знания в 1ADK — это утверждение вместе со ссылкой на источник. Любое высказывание продукта о вашей системе можно довести до файла и диапазона строк, которые человек с вашей стороны откроет и посмотрит сам.

{
  "entities": [
    { "key": "svc.payments", "type": "SERVICE", "name": "PaymentService",
      "description": "Создаёт и меняет платёжные операции.",
      "repository_path": "app/Services/PaymentService.php" }
  ],
  "evidence": [
    { "key": "ev.create", "kind": "CODE_REFERENCE",
      "summary": "Где создаётся платёж.",
      "locator": { "path": "app/Services/PaymentService.php", "lines": "40-88" },
      "confidence": "HIGH" }
  ],
  "claims": [
    { "about": "op.create", "predicate": "idempotency",
      "value": "Повтор запроса с тем же ключом возвращает первый платёж.",
      "perspective": "OBSERVED", "evidence": ["ev.create"] }
  ],
  "unknowns": [
    { "question": "Что происходит с платежом, который провайдер так и не подтвердил?",
      "why_it_matters": "Деньги могут быть списаны, а записи о них не останется.",
      "priority": "HIGH", "about": "svc.payments" }
  ]
}

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

Охват фиксирует, что на самом деле смотрели. Если анализ пропустил vendor/, он об этом говорит. Поэтому 1ADK умеет отличать «этого компонента больше нет» от «в этот раз туда не заглядывали» — различие, которое на втором запуске оказывается неожиданно важным.

Открытые вопросы — это обязательный результат, а не провал. Инструкция так и говорит агенту: пустой список вопросов после одного прохода по живой системе означает догадку, а не находку. Почему незнание — это тоже результат — о том, что это даёт.

#Что происходит после того, как оно пришло

Одинаково, загрузил ли файл человек или его прислала подключённая машина. Сервер не доверяет одному больше, чем другому.

1. Карантин

   Байты попадают туда, где нет ни одного хранилища проекта и куда остальной продукт не заглядывает. Ничего ещё не разобрано.

2. Проверка

   Файл сверяют со схемой пакета, ограничением по размеру и тем заданием, к которому он себя относит. Свободный текст просматривают на формы, которые обычно принимают учётные данные: bearer-заголовок, ключ AWS, начало приватного ключа. Пакет с такой находкой отклоняют целиком.

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

3. Ваше решение

   Проверенное описание ждёт. Вы видите, что в нём: количества, охват, ограничения, о которых заявил сам агент, — и либо одобряете его, либо выбрасываете. Одобрение даётся на конкретное описание и всегда явно.

4. Запись

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

Знание каждого проекта живёт в собственном изолированном хранилище. Два проекта не делят одну базу, и в продукте нет запроса, способного прочитать сразу оба. У публичного сайта, который вы сейчас читаете, доступа ко всему этому нет вообще: это отдельное приложение, у которого нет ни одного доступа к базе платформы.

#Что вы получаете

• Продукт Карта системы Карта системы — это структурированный ответ на вопрос, из чего состоит программа и как её части связаны между собой. Что в неё входит, что делает её достоверной и чем она отличается от архитектурной схемы. Что такое карта программной системы?
• Продукт Доказательства Каждое утверждение 1ADK несёт файл, диапазон строк или конфигурацию, из которых оно взято. Что такое доказательство, что означает уверенность и почему проверяемое утверждение лучше уверенного объяснения. Как проверить, правда ли то, что сказано о моей системе?
• Продукт Неизвестное Неизвестное — это результат, а не сбой. Почему «не найдено» не равно «этого нет», как открытый вопрос записывается и закрывается и почему документ без пробелов должен вас насторожить. Как документировать то, чего о системе никто не знает?
• Продукт История изменений Сравнение двух анализов одной системы даёт четыре разных ответа: появилось, изменилось, исчезло и больше не подтверждается. Почему именно четвёртый — причина продолжать анализировать. Как отследить, что меняется в архитектуре моей системы?

Быстрее всего судить об этом, открыв готовое. Демонстрационный проект — это полностью разобранная система, вымышленная и подписанная как вымышленная на каждом экране, показанная теми же страницами, которыми пользуется настоящий клиент. Аккаунт не нужен.

#Второй запуск

Именно этот раздел решает, стоит ли продукт чего-нибудь после первой недели.

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

• Появилось — компонент, которого в прошлом анализе не было.
• Изменилось — тот же компонент, описанный иначе.
• Исчезло — и только там, где охват позволяет это утверждать. Если второй анализ в этот каталог не заглядывал, 1ADK не скажет, что компонент удалили.
• Больше не подтверждается — утверждение, которое делали раньше и которое ничем в текущей картине не поддержано. Его не удаляют: его помечают как то, во что раньше верили.

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

#Чего это не делает