A1sCode библиотека 1С

🤖 AGENTS.md — Инструкции для ИИ-агентов

Один файл, который научит Claude, Cursor, Copilot и Codex правильно работать с A1sCode. Больше никаких выдуманных функций!

🎭 Знакомьтесь: 🐱 Кот Айван покажет, как ИИ работает с AGENTS.md, а 🦊 Лис Тинг — что бывает без него.

📥 Скачать AGENTS.md 📖 Спецификация agents.md

📄 Что такое AGENTS.md?

AGENTS.md — это стандартный файл инструкций для AI-агентов, разработанный сообществом (OpenAI, Sourcegraph, Google). Он размещается в корне проекта и содержит:

📋 Описание проекта

Философия, архитектура, ключевые модули

⚙️ Реальные функции

Только существующие API с примерами

⚠️ Критичные правила

Что НИКОГДА нельзя делать

🔗 Ссылки на стандарты

Где искать полную документацию

🦊 Проблема: ИИ выдумывает функции

Без AGENTS.md ИИ-агенты часто генерируют несуществующий код, основываясь на «здравом смысле»:

❌ ИИ выдумал (НЕ РАБОТАЕТ):

// Fluent-стиль — НЕ реализован!
Таблица = A1sVT.Н("Код,Наименование").Д("001", "Товар").СК("Код");

// Несуществующие функции
Запись = A1sIR.П("КурсыВалют", Фильтр);  // П() не существует
A1sIR.З("Настройки", Данные);             // З() не существует

🦊 Лис Тинг: «Я потратил 2 часа, пытаясь понять почему код от ChatGPT не компилируется. Оказалось, функций A1sVT.Н() и A1sIR.П() просто не существует!»

🐱 Решение: AGENTS.md в корне проекта

С AGENTS.md ИИ знает реальные функции и генерирует рабочий код:

✅ ИИ генерирует правильно:

// Раздельные вызовы — как в реальном API
Таблица = A1sVT.Of("Код:Строка,Наименование:Строка");
A1sVT.AddRow(Таблица, A1sDS.Of("Код", "001", "Наименование", "Товар"));

// Реальные функции A1sIR
Запись = A1sIR.Read("КурсыВалют", A1sDS.Of("Валюта", USD));
A1sIR.Write("Настройки", A1sDS.Of("Ключ", "Значение"));

🐱 Кот Айван: «Теперь Claude видит AGENTS.md и использует только реальные функции: Of(), AddRow(), Read(), Write(). Код работает с первого раза!»

🚀 Как использовать AGENTS.md

Шаг 1: Скачайте файл

📥 Скачать AGENTS.md

Шаг 2: Разместите в корне проекта

📁 МойПроект1С/
├── 📄 AGENTS.md          ← Инструкции для ИИ
├── 📁 src/
│   ├── A1sVT.bsl
│   ├── A1sDS.bsl
│   ├── A1sIR.bsl
│   └── A1sQ.bsl
└── 📁 docs/

Шаг 3: ИИ автоматически прочитает файл

Большинство современных ИИ-агентов автоматически ищут AGENTS.md в корне проекта:

🤖 Поддерживаемые ИИ-агенты

🟠

Claude (Anthropic)

Читает AGENTS.md автоматически в Claude Code и через Projects.

Как подключить:
  1. Откройте Claude Projects
  2. Добавьте AGENTS.md в Project Knowledge
  3. Claude будет следовать инструкциям
🟣

Cursor IDE

Автоматически индексирует AGENTS.md и .cursorrules.

Как подключить:
  1. Положите AGENTS.md в корень проекта
  2. Cursor автоматически его найдёт
  3. Или создайте .cursorrules с тем же содержимым
🟢

GitHub Copilot

Использует контекст из открытых файлов и репозитория.

Как подключить:
  1. Держите AGENTS.md открытым в редакторе
  2. Или используйте Copilot Chat с @workspace
  3. Copilot учтёт контекст файла
💬

ChatGPT / Codex

Вставьте содержимое AGENTS.md в начало диалога или Custom Instructions.

Как подключить:
  1. Скопируйте содержимое AGENTS.md
  2. Вставьте в Custom Instructions
  3. Или в начало каждого диалога

📋 Что содержит AGENTS.md для A1sCode

🏗️ Архитектура

  • Префикс модулей: A1s
  • Философия: 80% сокращение кода
  • Платформа: 1С 8.3.20+
  • Кодировка: UTF-8 BOM

📦 Модули и функции

  • A1sDS: Of(), OfPick(), Merge()...
  • A1sVT: Of(), AddRow(), Filter()...
  • A1sIR: Read(), Write(), GetSlice()...
  • A1sQ: Q(), Unload(), ValueQ()...

⚠️ Критичные правила

  • Fluent-стиль НЕ реализован
  • Проверка типов: Тип("...КлючЗаписи.ИмяРегистра")
  • Не выдумывать функции
  • Сверяться с реальным кодом

🔗 Ссылки на стандарты

💬 Пример диалога с ИИ

👤

Разработчик: Создай функцию для записи курса валюты в регистр сведений

🤖

Claude (с AGENTS.md): Вот функция с использованием A1sIR:

Процедура ЗаписатьКурсВалюты(Валюта, Курс, Дата) Экспорт
    
    // Используем A1sIR.Write() для записи в регистр
    A1sIR.Write("КурсыВалют", A1sDS.Of(
        "Валюта", Валюта,
        "Период", Дата,
        "Курс", Курс,
        "Кратность", 1
    ));
    
КонецПроцедуры

Примечание: A1sIR.Write() автоматически использует транзакцию (SafeMode=True по умолчанию). Для проверки типа ключа записи используйте Тип("РегистрСведенийКлючЗаписи.КурсыВалют").

⚖️ Сравнение: без AGENTS.md vs с AGENTS.md

🦊 Без AGENTS.md

  • ❌ ИИ выдумывает функции
  • ❌ Fluent-синтаксис не работает
  • ❌ Неправильные сигнатуры
  • ❌ Код не компилируется
  • ❌ Часы на отладку
// ИИ сгенерировал (НЕ РАБОТАЕТ)
Таб = A1sVT.Создать("Код,Имя")
    .ДобавитьСтроку("1", "Тест")
    .Отфильтровать("Код=1");

🐱 С AGENTS.md

  • ✅ Только реальные функции
  • ✅ Правильный синтаксис
  • ✅ Верные сигнатуры
  • ✅ Код работает сразу
  • ✅ Экономия времени
// ИИ сгенерировал (РАБОТАЕТ)
Таб = A1sVT.Of("Код,Имя");
A1sVT.AddRow(Таб, A1sDS.Of("Код","1","Имя","Тест"));
Результат = A1sVT.Filter(Таб, A1sDS.Of("Код","1"));

❓ Частые вопросы

Зачем нужен отдельный файл, если есть документация?

AGENTS.md — это компактная выжимка специально для ИИ. Документация на сайте подробная и для людей, а AGENTS.md содержит только критичную информацию в формате, который ИИ легко парсит.

Как часто обновлять AGENTS.md?

При каждом изменении публичного API модулей. Добавили новую функцию в A1sVT? Обновите AGENTS.md. Это гарантирует, что ИИ всегда знает актуальные функции.

Можно ли использовать с другими библиотеками 1С?

Да! Формат agents.md универсален. Создайте свой AGENTS.md для любой библиотеки или проекта — опишите модули, функции, ограничения, и ИИ будет генерировать правильный код.

Что если ИИ всё равно выдумывает функции?

Убедитесь, что AGENTS.md загружен в контекст. В Claude — добавьте в Project Knowledge. В Cursor — проверьте, что файл в корне. В ChatGPT — вставьте содержимое в начало диалога с пометкой «Следуй этим инструкциям».

🚀 Начните использовать AGENTS.md сегодня

Один файл сэкономит часы отладки и сделает работу с ИИ предсказуемой

📥 Скачать AGENTS.md 📖 Стандарты A1sCode