Короткий ответ
#Что здесь значит «доказательство»
- Доказательство
- Запись о том, откуда взялась находка: путь в репозитории, диапазон строк, символ, ключ конфигурации или документ, вместе с короткой сводкой о том, что там было. Доказательство никогда не содержит сам источник — это указатель и фраза, а не копия.
- Если проще Чек за утверждение — где это было найдено, чтобы кто-то другой мог пойти и посмотреть.
Это маленькая идея с большим следствием. Она означает, что техническое утверждение о вашей системе перестаёт быть вопросом доверия к тому, кто его написал, и становится тем, что человек закрывает за минуту, открыв файл.
#Почему это важнее, чем звучит
Способ ломаться, который это убирает, вполне конкретен, част и дорог.
Попросите любого толкового инженера — или любого толкового кодового агента — объяснить систему, которую он только что прочитал, и вы получите гладкий, хорошо организованный ответ. Часть его будет ровно верна. Часть будет разумным выводом из названий, соглашений фреймворка и формы. Обе части приходят одним и тем же голосом.
Для читателя, который не может их различить, — владельца, нового технического директора, команды, принимающей систему, — это не мелочь. Он примет решение, которое зависит от того, из какой половины пришла конкретная фраза, и у него нет способа это выяснить.
Доказательство и делает это различимым. Под фразой «платежи повторяются три раза» либо есть файл и диапазон строк, либо нет, и читатель видит, что именно.
#Из чего состоит утверждение
Внутри проекта 1ADK утверждение — не абзац. Это небольшая структура из четырёх частей, и именно она позволяет сравнить два анализа и сказать, что утверждение больше не подтверждается.
| Часть | Смысл | Пример |
|---|---|---|
| О чём | Предмет утверждения | Операция «создать платёж» |
| Свойство | Какое свойство описывается | Идемпотентность |
| Значение | Само утверждение, человеческими словами | «Повтор запроса с той же ссылкой возвращает первый платёж». |
| Доказательство | Где это установлено | app/Services/PaymentService.php, строки 40–88 |
#Факт, наблюдение, вывод
Три разных вида высказывания, разделённые, а не смешанные.
Каждое утверждение записывает ещё и то, как в него поверили. Это различение большинство технических документов теряет, и именно оно важно, когда кто-то решает, действовать ли.
- Наблюдалось — это прочитано прямо в системе. Самый сильный вид: код делает так.
- Заявлено — кто-то так сказал. README, комментарий, спецификация, человек. Записывать стоит, и это не то же самое, что наблюдалось: заявление может устареть, оставаясь прекрасно читаемым.
- Выведено — получено из соглашений, названий или формы, а не прочитано напрямую. Часто верно. Никогда не должно считаться наблюдением.
Расхождение между заявленным и наблюдаемым — одна из самых полезных вещей, которые техническая картина может показать: это спецификация говорит одно, а программа делает другое, — ровно там и живут дорогие сюрпризы.
#Что такое уверенность и чем она не является
У утверждений есть уровень уверенности — высокий, средний, низкий. Это высказывание о том, насколько твёрдо доказательство поддерживает утверждение, и ни о чём другом.
Это не оценка
Уверенность — не процент, не рейтинг здоровья и не число, которое усредняют в цифру на дашборде. «Ваша система набрала 73 из 100» — фраза, которая ничего не значит и прячет всё, что было бы полезно. 1ADK такой не выдаёт.
Смежная идея — свежесть: как давно собрано доказательство и подтверждает ли его последний анализ. Утверждение с высокой уверенностью из анализа семимесячной давности — это утверждение с высокой уверенностью о том, что было семь месяцев назад.
#Утверждение, разобранное на части
УТВЕРЖДЕНИЕ Повтор запроса с той же ссылкой возвращает первый
платёж, а не создаёт второй.
О ЧЁМ Создание платежа · POST /api/payments
ПРИРОДА Наблюдалось
УВЕРЕННОСТЬ Высокая
ДОКАЗАТЕЛЬСТВО app/Services/PaymentService.php:40-88
«Место, где создаётся платёж».
СВЯЗАННОЕ НЕИЗВЕСТНО · Не найден тест, который проходил бы
по пути повторного запроса.Обратите внимание, что читатель теперь может то, чего не мог раньше: не согласиться предметно. «Я открыл эти строки, там не это» — разговор, который заканчивается верным ответом. «Мне кажется, это неправда» — нет.
#Почему с ИИ в контуре это важнее
Кодовые агенты сделали правдоподобное техническое объяснение системы сильно дешевле. Это по-настоящему полезно и меняет экономику понимания программ. Это же означает, что предложение уверенных, хорошо написанных и отчасти неверных технических документов выросло чудовищно.
Позиция 1ADK не в том, что агентам не надо доверять, — продукт построен на агенте. Она в том, что вывод агента должен быть проверяемым, а непроверенное утверждение должно выглядеть иначе, чем проверенное. Ровно поэтому инструкция анализа требует указателей на источники, запрещает исходный код в выводе и требует сообщать о неизвестном, а не заполнять его.
Для владельцев, чьи системы во многом написаны агентами, есть смежная дисциплина: программа, написанная ИИ разбирает, что меняется, когда целую картину в компании не держал никто.
#Чего доказательство не доказывает
Чего это не делает
- Что код правильный. Доказательство показывает, что код делает, а не то, что так и задумывалось.
- Что анализ нашёл всё. Утверждение с доказательством хорошо обосновано; отсутствие утверждения не является доказательством отсутствия — для этого есть неизвестное и охват.
- Что доказательство всё ещё актуально. Указатель показывает на файл и строки такими, какими они были на определённом коммите. Строки сдвигаются.
- Что это читал человек. Доказательство фиксирует, откуда взялась находка, а не то, что кто-то старший с ней согласился. Человеческая проверка — отдельное явное состояние.