Контекст для ШІ-агентів вимірює, чи надає репозиторій ШІ-агентам для кодування настанови та машиночитану документацію. Агент, що потрапляє в незнайому кодову базу, стикається з тією ж проблемою, що й новий співробітник — тільки він читає ввідні матеріали за мілісекунди, у кожній сесії. Проєкти, які фіксують ці матеріали письмово, отримують вимірно кращі результати роботи агентів.
- Категорія: Готовність до ШІ (30% у межах категорії)
- Вага в загальному індексі: 1.2%
- Ключ метрики:
ai_agent_context
Як обчислюється значення
| Компонент | Вага | Підтвердження |
|---|---|---|
| Інструкції для агентів | 45 | CLAUDE.md, AGENTS.md, .cursor/rules, інструкції Copilot, GEMINI.md чи еквівалент; файл, менший за ~200 байтів, вважається заготовкою і отримує часткові бали |
| Машиночитана документація | 15 | наявний llms.txt або llms-full.txt |
| Зрозуміла історія комітів | 40 | частка людських комітів, які заявляють свій намір; повний бал від 75% і вище |
Чому історія комітів має значення
Письмові настанови — це файл, який хтось мусив вирішити створити, і в більшості проєктів його немає. Історія комітів інша: її створює кожен проєкт без винятку, і агент звертається до неї, перш ніж змінювати незнайомий код, — щоб дізнатися, чому було ухвалено рішення довкола, а не лише що робить код.
Коміт вважається таким, що заявляє свій намір, коли його заголовок структурований — у формі conventional commit або з посиланням на issue чи pull request, що стоїть за зміною, — або коли його тіло пояснює зміну, а не переказує заголовок. Зараховується будь-яка з форм, бо кожна вимога окремо була б вузькою: ядро Linux не пише conventional-префіксів і майже завжди пояснює себе, тоді як інші проєкти ведуть повністю conventional історію з однорядковими повідомленнями. Обидві зрозумілі; обидві зараховуються.
Коміти, зроблені автоматикою, виключаються, бо машинно згенеровані заголовки однаково добре сформовані й нічого не говорять про власну практику проєкту.
Що містить якісний контекст для агентів
Ефективний файл інструкцій розповідає агентові те, що README розповідає людині, а на додачу — те, що знають лише мейнтейнери: як зібрати й протестувати проєкт, які каталоги важливі, які в проєкті домовленості та де приховані пастки («контейнер обслуговує зібрані образи — після редагування потрібне перескладання»). Конвенція llms.txt доповнює це, надаючи мовним моделям упорядкований покажчик документації проєкту.
Правило про заготовки існує тому, що сигналами наявності можна маніпулювати: порожній CLAUDE.md, створений заради бейджа, помітно відрізняється від справжнього, і методологія враховує змістовність там, де її дешево виявити.
Як читати результат
- Сигнали ґрунтуються на наявності та розмірі файлів у дереві репозиторію; вміст не оцінюється — це чесно визнане обмеження, зазначене в усій категорії Готовність до ШІ.
- Зараховується будь-яка з визнаних конвенцій інструкцій; методологія нейтральна щодо постачальників агентських інструментів — так само, як стан безпеки не залежить від конкретних інструментів.
Як покращити значення
- Написати змістовний
CLAUDE.mdабоAGENTS.md: команди складання та тестування, структура, домовленості й відомі пастки. Підтримувати його актуальним — це документація з виконавчою аудиторією. - Додати
llms.txt, що індексує документацію проєкту для споживання мовними моделями. - Посилатися на issue чи pull request у заголовках комітів або пояснювати зміну в тілі. І те, й те — звичайна дисципліна рев'ю; і те, й те лишає історію зрозумілою для того — чи для чого, — що підтримуватиме проєкт далі.
Дивіться також: цикл верифікації для ШІ · Готовність до ШІ