Структурно-ориентированная кодовая база для агента

Агент, который ничего не знал

При первом запуске агент не знает структуру проекта. Из-за этого возникают проблемы:

1. Читает слишком много файлов и быстро расходует контекст.

2. Или, наоборот, не находит нужные файлы и места в коде.

Справочный файл

Один из способов снизить эти проблемы — создать справочный файл ./docs/reference.md, где описаны ключевые файлы проекта и их назначение.

Минусы:

• Вручную поддерживать сложно.

• Если генерировать описание агентом, то для конкретной задачи в нём часто не хватает деталей.

Кодовая база как собственная справка

Можно ввести правила оформления файлов и автоматически генерировать структуру проекта.

Какие правила можно добавить в AGENTS.md

1. Одна ответственность на файл: в каждом файле — одна задача. Имя файла должно прямо описывать назначение.

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

С содержанием комментария можно экспериментировать — добавлять зависимости, побочные эффекты, теги и т. п.

Два уровня: структура папки и структура файла

После этого можно написать скрипты, которые генерируют структуру проекта на двух уровнях.

Структура папки

Это индекс по файлам: где находится код и за что отвечает каждый файл. Скрипт проходит по src/**/* и собирает список: путь к файлу → комментарий в начале файла.

Пример для ./src:

src/cli/input-arguments.ts: CLI argument parsing and input path normalization helpers.
src/cli/modes.ts: CLI execution modes for file, glob, and debug workflows.
src/cli/types.ts: Shared CLI runtime types for dependency injection and content processing.
src/core/declaration-lines.ts: Shared helpers for converting parsed declarations into outline lines.
src/core/formatter.ts: Declaration formatting utilities for generating outline output.
src/core/header-comment-lines.ts: Shared helpers for rendering extracted header comments into outline lines.
src/core/language-engine.ts: Shared interface for language-specific outline generators.
src/core/language-registry.ts: Registry and resolver for language-specific outline engines.
src/core/outline-renderer.ts: Shared helpers for rendering structured outline lines.
src/core/types.ts: Core type definitions for outline generation.
src/debug/debug-mode.ts: Debug mode output generator for source highlighting. Provides ANSI-highlighted source output for debug view.
...
 [1]

Структура файла

Это список элементов верхнего уровня в файле. Скрипт извлекает только объявления верхнего уровня (функции, классы, константы, экспорты). Это помогает понять, что есть в файле, не читая его целиком.

Пример для comments.ts:

function stripBom(content: string): string
function findFirstContentLineIndex(lines: readonly string[]): number
function getLineStartPosition(lines: readonly string[], lineIndex: number): number
function extractSingleLineComments(lines: readonly string[], startIndex: number): string
export function extractTopComment(content: string): string | null
export function extractTopCommentLineNumber(content: string): number | null
export function cleanCommentText(comment: string): string
 [1]

По этим данным уже можно видеть, какой примерно функционал содержится в comments.ts.

Как использовать

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

• Структуру для src/ можно генерировать на каждый коммит и хранить в docs/. Бонусом — по изменениям можно следить за развитием проекта и видеть архитектурные изменения прямо в диффах.

Экономия

В моих тестах этот подход снижал расход токенов до 20% (в зависимости от задачи).

Как попробовать

• Вариант 1: попросите агента сделать скрипт, который (1) собирает комментарии в начале файлов и (2) выводит элементы верхнего уровня. Для разбора кода подойдёт tree-sitter.

• Вариант 2: используйте мой вариант скрипта https://github.com/ptol/outln ^[2] (поддерживает ts, js, go, rs, md)

Какие подходы вы используете для решения проблемы холодного старта агента в кодовой базе?