DeepSeek Harness: AGENTS.md не работает — разбор

В официальной документации API DeepSeek указаны контекст длиной 64 000 токенов и максимальный вывод до 8 000 токенов для перечисленных моделей; это не является фиксированным лимитом именно для AGENTS.md, но показывает, почему инструкции конкурируют с кодом, историей диалога и результатами инструментов. Параметры контекста и вывода в официальной документации

Симптом: файл AGENTS.md существует, но DeepSeek Harness продолжает нарушать правило или ведёт себя по-разному в соседних каталогах.

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

Кому пригодится этот разбор:

• разработчикам, которые уже создали AGENTS.md, но Agent игнорирует проектные нормы;
• техническим руководителям, поддерживающим инструкции в monorepo и нескольких уровнях каталогов;
• специалистам по эксплуатации, у которых после переноса рабочей среды на удалённый Mac изменилось поведение правил.

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

Почему файл найден на диске, но правило не действует

Факт существования файла и факт его попадания в workspace context — разные события. В типичном отказе разработчик открывает AGENTS.md в редакторе, видит правильное имя и делает вывод, что DeepSeek Harness должен его использовать. Однако загрузчик может начинать поиск не из той папки, считать корнем другой каталог, выбрать иной кандидат или не включить содержимое в новую сессию.

Проверяйте как минимум четыре независимых ограничения.

1. Рабочая папка запуска. Команда dsh могла быть выполнена из родительского каталога, временной копии или симлинка, тогда как в Web UI выбран другой workspace.
2. Распознавание корня проекта. Если маркер корня не найден или настроен не там, поиск может продолжиться выше ожидаемого каталога. В результате Agent получает правила соседнего проекта либо общий пользовательский файл.
3. Набор кандидатов. Глобальная инструкция, проектный AGENTS.md, локальный файл и CLAUDE.md могут рассматриваться как разные источники, а не как один документ. Нельзя делать вывод о порядке объединения по одному успешному запуску.
4. Жизненный цикл сессии. Изменение файла после старта не доказывает, что текущий диалог перечитал его. История уже содержит прежний набор правил и может продолжать влиять на ответы.

У самого проекта DeepSeek Harness в публичном описании показан сценарий чтения AGENTS.md из рабочей папки, но пример интерфейса не заменяет проверку конкретной версии загрузчика в вашей среде. Пример работы с AGENTS.md в репозитории проекта

DeepSeek Harness загружает AGENTS.md автоматически или только после явной команды?
Не делайте универсального вывода без проверки версии и режима запуска. В минимальном тесте попросите Agent назвать путь к обнаруженному файлу и воспроизвести уникальное безопасное правило. Если он лишь отвечает «я буду соблюдать инструкции», это не доказательство загрузки: такая фраза может быть сгенерирована из вашего запроса.

Надёжнее использовать правило, не меняющее код и не запускающее опасные команды. Например, добавьте в тестовый AGENTS.md требование: перед ответом по проекту выводить маркер PROJECT-RULE-CHECK-7, а затем попросите перечислить корень проекта и имя загруженного файла. После этого удалите маркер из постоянной инструкции, чтобы он не стал частью рабочего протокола.

Первый этап: зафиксируйте окружение до создания сессии

До запуска DeepSeek Harness запишите три значения:

• каталог, из которого вызывается dsh;
• workspace, выбранный в Web UI или переданный параметром запуска;
• фактический корень Git-репозитория либо другого проекта.

Не смешивайте логический workspace и текущий каталог shell. В удалённой среде они нередко различаются: интерфейс подключён к одному пути, терминальный процесс стартует в другом, а репозиторий смонтирован через симлинк.

Выполните безопасную проверку:

pwd
git rev-parse --show-toplevel
find .. -name AGENTS.md -o -name CLAUDE.md

Если проект не использует Git, замените вторую команду на проверку маркеров, которые ваша версия Harness считает признаком корня. Не подставляйте предполагаемые имена конфигурационных файлов: факт поддержки конкретного маркера нужно сверить с официальным каталогом конфигурации и документацией версии.

Затем создайте минимальный репозиторий, не содержащий бизнес-кода:

mkdir -p /tmp/dsh-instruction-test/project/src
cd /tmp/dsh-instruction-test/project
git init
printf '%s\n' '# Test project' > README.md

Положите AGENTS.md только в этот каталог и добавьте одну проверяемую директиву, например запрет редактировать README.md без предварительного объяснения. Не используйте в первом тесте сложные инструкции, ссылки на десятки документов и неоднозначные слова вроде «всегда работай аккуратно».

Критерий восстановления на этом этапе:

• команда запуска и корень проекта совпадают;
• Agent называет ожидаемый путь;
• уникальное правило воспроизводится в новой сессии;
• аналогичный запрос из соседнего каталога не получает это правило случайно.

Если один пункт не выполнен, переходить к настройке содержимого файла рано.

Как проверить кандидатов и конфликт AGENTS.md с CLAUDE.md

После подтверждения рабочей папки исследуйте не весь проект, а именно цепочку инструкций. Разложите источники по расположению:

• пользовательский или глобальный файл;
• файл в корне проекта;
• файл в текущем подкаталоге;
• локальная настройка workspace;
• дополнительные файлы, на которые ссылается инструкция.

Сохраните контрольный набор в отдельной заметке: абсолютный путь, размер файла, время изменения и короткий уникальный маркер. Не вставляйте в маркер секреты, токены или персональные данные.

for f in AGENTS.md CLAUDE.md ../AGENTS.md ../CLAUDE.md; do
  if [ -f "$f" ]; then
    printf '\n--- %s ---\n' "$f"
    wc -c "$f"
    shasum -a 256 "$f"
    sed -n '1,12p' "$f"
  fi
done

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

Что ожидать, если одновременно присутствуют AGENTS.md и CLAUDE.md?
Не предполагайте, что один файл обязательно имеет приоритет над другим. Официальная документация другого широко используемого coding-agent показывает, что CLAUDE.md может загружаться как проектный контекст, а не как системный prompt; это важное различие между «файл прочитан» и «правило имеет высший приоритет». Описание загрузки проектного CLAUDE.md

Для DeepSeek Harness проверяйте фактическое поведение вашей версии отдельными тестами:

1. только AGENTS.md;
2. только CLAUDE.md;
3. оба файла с разными безопасными маркерами;
4. оба файла с противоречащими, но безвредными правилами;
5. файл в корне и второй файл в дочернем каталоге.

Не называйте результат «приоритетом», пока не записали, какой текст был найден, в каком порядке он был передан и какой ответ получен. Повторяющееся правило может быть объединено, сокращено или визуально скрыто интерфейсом, поэтому отсутствие отдельной строки в окне не доказывает отсутствие содержания.

Вторая проверка: меняется ли набор правил в дочернем каталоге

Monorepo создаёт особенно много ложных диагнозов. Сессия, запущенная в корне, может видеть общие правила, а сессия из packages/api — дополнительно локальные. Возможна и обратная ситуация: из-за ошибочного корня Agent читает инструкции другого пакета и не видит корневой файл.

Сделайте два запуска с одинаковым запросом:

• первый — из корня репозитория;
• второй — из целевого подкаталога.

В каждом запуске попросите вывести только:

• текущую рабочую папку;
• распознанный корень;
• список обнаруженных файлов инструкций;
• уникальные маркеры каждого файла;
• правило, которое применяется к тестовой операции.

Не просите Agent сразу исправлять код. В противном случае результат смешает проблему загрузки с качеством выполнения задачи.

Проверяйте также симлинки и регистр букв. AGENTS.md, agents.md и файл, находящийся в другой копии репозитория, могут выглядеть одинаково в интерфейсе, но иметь разные пути. В macOS файловая система может скрывать часть таких различий при обычной визуальной проверке, поэтому используйте абсолютные пути и хеши.

Напоминание: если два файла содержат одинаковый текст, их «слияние» может быть незаметно. Для диагностики сначала используйте разные короткие маркеры, а после проверки верните единый редакционный вариант.

Критерий восстановления для monorepo — предсказуемый набор правил: корневой запуск получает общие ограничения, подкаталог получает только те дополнительные правила, которые действительно предназначены для него, а соседний пакет не влияет на результат.

Может ли размер или формат файла скрыть инструкцию

Если путь и иерархия подтверждены, переходите к содержимому. Здесь важно не придумывать фиксированный предел в байтах или строках: допустимый размер зависит от версии DeepSeek Harness, модели, режима и общего workspace context.

Официальная документация API прямо указывает, что общий объём входных и выходных токенов ограничен размером контекста, а слишком длинное содержимое может привести к обрезанию ответа или превышению доступного окна. Описание ограничения общего контекста и max_tokens

Проверьте четыре вещи:

• кодировку файла;
• наличие повреждённых или невидимых символов;
• читаемость для пользователя, под которым запущен процесс;
• объём файла вместе с остальным контекстом сессии.

file -I AGENTS.md
wc -l -c AGENTS.md
ls -lO AGENTS.md
python3 - <<'PY'
from pathlib import Path
p = Path("AGENTS.md")
data = p.read_bytes()
print("bytes:", len(data))
print("utf8:", end=" ")
try:
    data.decode("utf-8")
    print("yes")
except UnicodeDecodeError as e:
    print("no:", e)
PY

Разделите файл на две части:

• короткие стабильные ограничения: команды проверки, границы каталогов, правила безопасности;
• справочный материал: архитектурные заметки, длинные примеры, исторические решения и инструкции для редких задач.

В постоянном файле оставьте ссылки на справочные документы и условие, когда их читать. Это лучше, чем копировать весь фон в каждый запуск. Если после сокращения уникальное правило начинает работать, причина, вероятно, была в объёме или конкуренции контекста, а не в имени файла.

Для дополнительного контроля сравните ответ при пустой истории и при большой истории. В официальных параметрах API отдельно отображаются prompt_tokens, completion_tokens, total_tokens, а также попадание prompt в cache hit или cache miss; эти поля полезны для журналирования нагрузки, хотя сами по себе не доказывают, что AGENTS.md был найден. Состав полей usage в официальном API

Что делать после изменения AGENTS.md

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

1. продолжите старую сессию и попросите Agent назвать контрольный маркер;
2. создайте новую сессию в том же каталоге;
3. перезапустите процесс DeepSeek Harness и снова создайте сессию.

Фиксируйте до и после:

• хеш AGENTS.md;
• время изменения;
• рабочий каталог;
• идентификатор сессии;
• наблюдаемый ответ Agent;
• список прочитанных файлов, если интерфейс или журнал его показывает.

Если новая сессия видит изменение, а старая нет, это не проблема файлового наблюдателя. Это ожидаемое следствие уже собранного контекста либо истории диалога. Если не видит ни одна сессия, возвращайтесь к пути, правам и настройке кандидатов.

Для проверки используйте две редакции одного правила. Например, в первой версии потребуйте выводить RULE-A, затем замените на RULE-B. Запрос должен быть одинаковым и не требовать изменения файлов. После успешной проверки удалите тестовые маркеры.

Контрольный список перед эскалацией проблемы

• [ ] Зафиксирован абсолютный путь, из которого запускается dsh.
• [ ] Записан workspace, выбранный в интерфейсе.
• [ ] Подтверждён фактический корень репозитория.
• [ ] Проверены проектные и глобальные кандидаты AGENTS.md.
• [ ] Отдельно проверен CLAUDE.md, если он присутствует.
• [ ] В тестовых файлах установлены разные безопасные маркеры.
• [ ] Сравнены корень и минимум один дочерний каталог.
• [ ] Проверены кодировка, права чтения, размер и невидимые символы.
• [ ] Длинный справочный материал отделён от обязательных правил.
• [ ] Сравнены старая сессия, новая сессия и запуск после перезапуска процесса.
• [ ] Сохранены хеши и ответы до и после изменения.
• [ ] Для удалённой среды проверены переменные окружения и точки монтирования.

Как восстановить поведение после миграции на удалённый Mac

Почему после удалённого запуска проектные инструкции не загружаются?
Чаще всего меняется не сам текст файла, а окружение вокруг него: другой пользователь, другой DSH_HOME, иной путь workspace, права на каталог или копия репозитория без незакоммиченного AGENTS.md.

Порядок проверки должен быть таким:

1. выведите значение DSH_HOME, если оно используется вашей установкой;
2. подтвердите, под каким пользователем запущен процесс;
3. проверьте реальный путь репозитория и отсутствие лишнего уровня вложенности;
4. сравните права чтения файла и каталога;
5. убедитесь, что инструкция доставлена вместе с кодом, а не осталась только на локальном Mac;
6. выполните тот же минимальный тестовый запрос;
7. сравните результат с локальной сессией;
8. при расхождении создайте чистую удалённую сессию в заранее определённом каталоге.

Для диагностики прав можно использовать:

printf 'user: '; id -un
printf 'home: '; printf '%s\n' "$HOME"
printf 'dsh_home: '; printf '%s\n' "${DSH_HOME:-<не задан>}"
pwd
test -r AGENTS.md && echo "AGENTS.md: readable" || echo "AGENTS.md: not readable"

Не публикуйте в журнале значения API-ключей и содержимое приватных инструкций. Если окружение создаётся заново, полезно иметь короткий акт приёмки: путь workspace, путь корня, владелец файла, права чтения и результат контрольного задания. Для командной работы можно дополнительно сверить рекомендации из сценариев использования удалённых рабочих сред, но конкретные пути и переменные нужно проверять в вашей установке, а не копировать вслепую.

Если восстановить загрузку не удаётся, временно используйте чистый каталог с одной короткой инструкцией и новой сессией. Это даст рабочую точку сравнения и позволит отделить проблему доставки среды от конфликта файлов в основном monorepo. После этого верните дополнительные слои по одному.

Когда менять среду, а не переписывать правила

Если локальная машина и удалённый Mac дают разные результаты при одинаковом репозитории, проблема может быть в воспроизводимости окружения: разные пользователи, переменные, монтирования, права и версии запускающего процесса. Повторное редактирование AGENTS.md в такой ситуации лишь маскирует причину, а длинный prompt увеличивает стоимость проверки и усложняет понимание того, какой слой сработал.

Собственный Mac удобен, когда нагрузка постоянна, нужны физические интерфейсы или важен полный контроль над системой. Общая облачная машина дешевле на коротком тесте, но часто создаёт ограничения по доступу, изоляции проектов, стабильности рабочего каталога и восстановлению после перезапуска. В сравнении с этим аренда Mac через KVMFLUX полезна для временного DeepSeek Harness-стенда, миграционной проверки и воспроизводимого удалённого запуска: вы сначала подтверждаете workspace, DSH_HOME, права и чистую сессию, а затем решаете, нужна ли постоянная инфраструктура. Условия можно сверить на странице аренды Mac и доступных вариантов.

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

Читайте также

• Безопасный запуск DeepSeek Harness в GitHub Actions
• Изоляция среды и защита ИИ-агентов от выхода из песочницы
• Как устроены плагины и расширения для ИИ-агентов