Agentic Coding · RUПеревод редакции 7 октября 2026

Ограничения кода для агентов

Агенты изучают кодовую базу через агентный поиск — Grep, Read, Glob. Агенты видят только тот код, который явно нашли. Когда ограничения разбросаны по файлам, именно поиск определяет, что агент увидит, а что упустит.

Антипаттерн: разбросанные ограничения:

// File: services/auth.ts
function createUser(email: string, password: string) {
  return db.users.insert({ email, password: hashPassword(password) });
}

// File: config/validation.ts
const MIN_PASSWORD_LENGTH = 12; // ← Agent never searches for this file

Что происходит: агент ищет Grep("createUser") → читает services/auth.ts → генерирует код, принимающий пароли из трёх символов, потому что так и не увидел MIN_PASSWORD_LENGTH.

Промышленный паттерн: ограничения рядом с кодом:

// File: services/auth.ts
const MIN_PASSWORD_LENGTH = 12; // ← Agent sees this in same file

function createUser(email: string, password: string) {
  if (password.length < MIN_PASSWORD_LENGTH) {
    throw new Error(
      `Password must be at least ${MIN_PASSWORD_LENGTH} characters`
    );
  }
  return db.users.insert({ email, password: hashPassword(password) });
}

Что происходит: агент ищет Grep("createUser") → читает services/auth.ts → при том же чтении видит MIN_PASSWORD_LENGTH → генерирует код, который соблюдает ограничение.

Семантические мосты, когда DRY требует разделения​

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

// File: shared/constants.ts
// Password strength requirements: minimum character length enforcement
export const MIN_PASSWORD_LENGTH = 12;

// File: services/auth.ts
import { MIN_PASSWORD_LENGTH } from '@/shared/constants';

// User credential validation: enforce security constraints
function createUser(email: string, password: string) {
  return db.users.insert({ email, password: hashPassword(password) });
}

Как работают семантические мосты: семантический поиск сопоставляет смысл, а не точные слова. Запрос «password validation requirements» находит ОБА файла, потому что эмбеддинги распознают смысловое сходство:

  • «password» ≈ «credential» — пароль и учётные данные;
  • «requirements» ≈ «constraints» — требования и ограничения;
  • «strength» ≈ «security» — стойкость и безопасность.

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

Автоматизируй с помощью промптов​

Вместо ручного управления стратегиями обнаруживаемости настрой агента так, чтобы он делал это автоматически. Добавь инструкции вроде "Document inline when necessary" («При необходимости документируй прямо в коде») и "Match surrounding patterns and style" («Следуй окружающим паттернам и стилю») в CLAUDE.md или AGENTS.md (инженерия контекста). Эти фразы заставляют агентов автоматически добавлять комментарии — семантические мосты при генерации, следовать существующим соглашениям в коде и сохранять согласованность без явного надзора. Во время исследования кода агент читает ограничения, размещённые рядом, и семантические мосты, а затем генерирует новый код по тем же паттернам, превращая обнаруживаемость в самоподдерживающуюся систему вместо ручной организационной работы.

Оговорка: время от времени придётся напоминать агенту об этих инструкциях в промптах для конкретной задачи. Из-за U-образной кривой внимания инструкции, спрятанные в конфигурационных файлах, в ходе длинных взаимодействий могут попасть в игнорируемую середину контекстного окна. Короткое напоминание вроде «при необходимости документируй прямо в коде и следуй окружающему стилю» в конце промпта удерживает эти ограничения в зоне высокого внимания.

Главные выводы​

  • Размещай ограничения рядом, а при необходимости создавай семантические мосты — разрозненность кода накапливается и усложняет навигацию по кодовой базе. Если разделение необходимо ради DRY, используй явные комментарии, указывающие на связанные файлы.
  • Автоматизируй обнаруживаемость с помощью промптов — добавь в AGENTS.md инструкции, по которым агенты автоматически создают семантические мосты и следуют паттернам, превращая обнаруживаемость в самоподдерживающуюся систему.
← ПредыдущаяСледующая →