Skip to content

Instantly share code, notes, and snippets.

@SoundBlaster
Last active May 3, 2026 11:02
Show Gist options
  • Select an option

  • Save SoundBlaster/fb50c0383ffea9f916f182b091bf15f4 to your computer and use it in GitHub Desktop.

Select an option

Save SoundBlaster/fb50c0383ffea9f916f182b091bf15f4 to your computer and use it in GitHub Desktop.
Code Smells and “Rot” in agentic programming

Да — идея хорошая, но я бы формулировал её не как «всегда думай дальше задачи», а как bounded scout mode: “улучшай вокруг себя, но только когда это дешево, локально, проверяемо и не раздувает diff; всё крупное — выноси в предложения/долг”.

Главный вывод после поиска: так уже пробуют, но зрелые практики почти везде добавляют ограничения. Просто “предлагай архитектурные улучшения всегда” быстро превращается в шум, самодеятельность и неконтролируемые рефакторинги.

Что нашлось по сути проблемы

Твоя интуиция про «локальную оптимизацию → гниение кодовой базы» хорошо совпадает с тем, что сейчас начинают мерить. В свежем preprint-исследовании “Debt Behind the AI Boom” авторы проанализировали 302.6k подтверждённых AI-authored commits из 6,299 GitHub-репозиториев; нашли 484,366 distinct issues, причём 89.3% — code smells, а 22.7% отслеженных AI-introduced issues дожили до последней версии репозитория. Это прямо про то, что часть долгов не “самоисправляется”, а остаётся в базе. 

Есть и более концептуальная работа про vibe coding: авторы описывают “flow-debt trade-off” — быстрый flow генерации кода накапливает долг через архитектурные несогласованности, security issues, отсутствие явного design rationale и maintenance overhead.  Sonar в своём 2026-отчёте/разборе пишет похожее на уровне self-report: 88% разработчиков сообщили хотя бы об одном негативном влиянии AI на tech debt; 53% — о коде, который выглядит правильным, но ненадёжен; 40% — о ненужном или дублирующем коде. 

Интересный нюанс: агенты уже умеют рефакторить, но в основном локально. В исследовании agentic refactoring по 15,451 refactoring instances авторы пишут, что агенты явно целились в refactoring в 26.1% коммитов, но их изменения в основном низкоуровневые: типы переменных, параметры, renaming, consistency-oriented edits; это скорее “уборка по месту”, чем human-level архитектурное переосмысление.  Ещё одно исследование readability-focused commits показало даже неприятный эффект: такие AI-коммиты часто ухудшали традиционные метрики — Maintainability Index снизился в 56.1% коммитов, Cyclomatic Complexity выросла в 42.7%. То есть “модель решила улучшить читаемость” не всегда означает, что код реально стал лучше. 

Отдельно важна метрика “работает ≠ хорошо спроектировано”. В апрельском preprint про большие проекты, сгенерированные Cursor, средняя functional correctness была 91%, но статанализ нашёл 1,305 design issues в CodeScene и 3,193 issues в SonarQube; среди частых проблем — duplication, high complexity, large methods, exception-handling issues, accessibility issues. 

Кто-то уже пробовал такие промты?

Да. Не всегда именно словами “Boy Scout Rule”, но паттерн уже стал частью agentic coding workflows.

В документации Claude Code прямо рекомендуют: дать агенту способ проверить работу, сначала исследовать, потом планировать, потом кодить, а не сразу бросаться менять файлы. Там же есть важная мысль: vague prompt вроде “what would you improve in this file?” может быть полезен именно в exploratory-сценарии, когда ты готов course-correct’ить.   Но та же документация предупреждает, что CLAUDE.md должен быть коротким и практичным; self-evident правила вроде “write clean code” лучше не писать, потому что раздутые инструкции агент начинает игнорировать. 

У Codex похожая модель: reusable guidance через AGENTS.md, где описываются layout репозитория, команды сборки/тестов, conventions, constraints, “done means”. В best practices также отдельно сказано не останавливаться на генерации кода: просить тесты, проверки, type/lint, review diff на баги, регрессии и risky patterns.   А use case “Refactor your codebase” у Codex формулируется как dead code / duplicated logic / stale patterns small reviewable passes, то есть не “разнеси архитектуру по красоте”, а маленькие обозримые проходы. 

Cursor тоже рекомендует rules как persistent instructions, но с тем же ограничителем: держать rules сфокусированными на essential commands, patterns, canonical examples; не копировать целые style guides, не документировать всё подряд, добавлять rules только после повторяющихся ошибок агента.  GitHub Copilot Code Review позволяет задавать custom review instructions через .github/copilot-instructions.md; пример из документации — просить review фокусироваться на readability и избегать nested ternaries. 

Самый близкий к твоей идее живой пример я нашёл в CLAUDE.md репозитория METR inspect-action: там буквально есть “Scout mindset — Fix what’s requested + low-cost cleanup”, а дальше правила: делать уборку в том же файле/функции, если это typos, unused imports, obvious bugs, genuinely confusing variable names, missing type hints; но ask first / suggest separately для function signatures, abstractions, restructuring modules/files, unrequested features.  Это, на мой взгляд, почти идеальная формулировка.

Есть и исследования самой практики rule/context files. Одно исследование Cursor Rules по 401 open-source репозиторию говорит, что разработчики уже кодируют project constraints, conventions, guidelines, project information, LLM directives и examples в persistent machine-readable directives.  Другое исследование конфигурации agentic coding tools по Claude Code, Copilot, Cursor, Gemini и Codex нашло, что context files доминируют, а AGENTS.md становится интероперабельным стандартом. 

Как я бы это оформил

Я бы не писал:

Всегда думай шире задачи. Предлагай архитектурные и стилистические улучшения, даже если они не касаются задания.

Это слишком открывает шлюз. Хорошая модель начнёт делать лишнее; средняя — будет галлюцинировать “архитектурные улучшения”; плохая — перепишет пол-экрана ради кнопки.

Я бы писал так:

Engineering mindset

Before editing, inspect the surrounding code and understand how the requested change fits existing patterns. Implement the requested change first. Apply Boy Scout cleanup only when all of these are true:

  • the cleanup is in the same file/function/component you are already touching;
  • it is low-risk and behavior-preserving;
  • it is easy to review;
  • it does not change public APIs, architecture, module boundaries, dependencies, or unrelated behavior;
  • it is covered by existing tests/lint/type checks, or can be verified cheaply. Encouraged low-cost cleanup:
  • remove unused imports/dead local code;
  • fix obvious naming confusion;
  • remove duplicated local logic;
  • fix typos in comments/docs;
  • align with existing style in the same file;
  • add a small missing test only when directly relevant. Do not perform broad refactors unless explicitly requested. Instead, report them under “Refactor opportunities” with:
  • file/location;
  • observed smell;
  • why it matters;
  • suggested next step;
  • risk/size estimate;
  • confidence. Before finishing:
  • run the narrowest relevant tests/checks;
  • review your own diff for regressions, duplication, style drift, and architectural mismatch;
  • summarize functional changes separately from cleanup.

Для iOS/Swift я бы добавил более предметные правила:

iOS-specific checks

For UI changes:

  • verify Dynamic Type / accessibility impact when relevant;
  • avoid hard-coded design values if the surrounding code uses design tokens;
  • follow existing SwiftUI/UIKit patterns in the file;
  • do not introduce a new architecture style for a local UI tweak;
  • mention snapshot/UI test opportunities separately unless the project already has a clear pattern.

Про “стучать на код”

Идея хорошая, но я бы не просил модель расставлять TODO прямо в коде по каждому запаху. Это быстро превращается в мусор: код начинает выглядеть хуже, а TODO без владельца и срока — это просто новая форма долга.

Лучше завести один из вариантов:

.refactor-opportunities.md

или секцию в PR summary:

Refactor opportunities noticed

  1. ProfileView.swift
    • Smell: duplicated layout constants in three button rows.
    • Why it matters: future design tweak will need multiple edits.
    • Suggested next step: extract local ButtonRowStyle or use existing design token.
    • Size: S
    • Risk: low
    • Confidence: high

Ещё лучше — разделить “делать” и “доносить”:

When you notice code smells:

  • Fix immediately only if it qualifies as low-cost scout cleanup.
  • Otherwise do not modify code. Add a short refactor note in the final response or debt log.
  • Never add TODO comments unless the TODO is specific, actionable, and directly related to the touched code.

Так агент не будет молча расширять scope, но начнёт давать сигнал, что рядом пахнет.

Мой вывод

Твоя мысль правильная: агента надо учить не только решать задачу, но и поддерживать здоровье системы. Но в базовом промпте важна не максимальная инициативность, а дисциплина инициативности.

Лучший режим выглядит так:

  1. Task first — сначала точное выполнение запроса.
  2. Bounded scout cleanup — маленькая локальная уборка, если она очевидна и безопасна.
  3. Separate refactor notes — всё крупнее выносится в список возможностей, не в diff.
  4. Verification — тесты, lint/typecheck, self-review.
  5. Durable rules — AGENTS.md, CLAUDE.md, .cursor/rules, .github/copilot-instructions.md, но короткие и конкретные.

И самое важное: “думай дальше” должно означать не “делай больше”, а “замечай больше, но меняй только то, что безопасно менять сейчас”.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment