Hacker News Digest

DeepWiki — это инструмент для индексации кода репозиториев, позволяющий "общаться" с их документацией через AI. Сервис использует Devin для анализа кода и предоставляет интерфейс для вопросов о любом проекте. Пользователи могут добавлять как публичные, так и приватные репозитории, получая мгновенные ответы по их структуре и функционалу. Это упрощает понимание сложных кодовых баз и ускоряет онбординг новых разработчиков.

На платформе уже доступны популярные репозитории, включая Microsoft VS Code (170k звёзд), Hugging Face Transformers (143k), LangChain (106k), SQLite (7.7k) и многие другие. DeepWiki позиционируется как решение для быстрого погружения в любой код без необходимости изучения документации вручную.

• Пользователи жалуются на качество автогенерируемой документации: она устаревшая, путает детали реализации с пользовательским API и содержит ошибки.
• Некоторые участники считают, что если проект и так плохо документирован, то LLM-инструменты не спасут ситуацию, а другие указывают, что даже при наличии хорошей документации LLM может давать неверные сводки.
• Обсуждается, что вместо попыток «автоматически документировать» код, лучше встроить LLM в IDE/editor и дать разработчику возможность взаимодействовать с LLM в процессе написания кода.
• Поднимается вопрос о том, что если проект не имеет достойной документации, то LLM не сможет помочь, и что вместо этого лучше встроить LLM в IDE/editor и дать разработчику возможность взаимодействовать с LLM в процессе написания кода.

Команда Material for MkDocs, известная своей популярной темой для документации, представила Zensical — современный генератор статических сайтов. Инструмент создан с упором на производительность и удобство использования, предлагая разработчикам альтернативу для создания быстрых и безопасных веб-сайтов. Zensical позиционируется как решение, сочетающее простоту настройки с расширенными возможностями кастомизации.

Хотя подробная документация еще в разработке, проект уже доступен на GitHub и привлекает внимание сообщества своей философией минимализма и оптимизации. Команда подчеркивает, что Zensical наслед лучшие практики Material for MkDocs, предлагая знакомый опыт работы для существующих пользователей. Инструмент ориентирован на создание документации, блогов и других типов контента с акцентом на скорость загрузки и безопасность.

• Пользователи обсуждают переход с Material for MkDocs на Zensical, включая вопросы о совместимости, плагинах и внешнем виде.
• Создатели Zensical объясняют, что это новый проект, а не форк, и что они стараются сохранить совместимость, но не могут гарантировать это для всех плагинов и тем.
• Обсуждается, что Zensical пока не поддерживает блоги и RSS, но это может быть добавлено в будущем.
• Пользователи спрашивают о PDF-экспорте, и создатели отвечают, что это в приоритете, но пока не реализовано.
• Создатели Zensical говорят, что они работают над WYSIWYG-редактором и улучшенным поиском, которые будут доступны в будущем.
• Некоторые пользователи выражают обеспокоенность по поводу того, что Zensical не является open-source, и что это может повлиять на их способность вносить вклад в проект.

Cognition представила Windsurf Codemaps — AI-аннотированные структурные карты кода, которые помогают разработчикам понимать свои проекты перед тем, как вносить изменения. В отличие от большинства AI-инструментов, которые увеличивают разрыв между программистом и его кодом, Codemaps нацелены на углубление понимания. Как отмечает Пол Грэм: "Ваш код — это ваше понимание проблемы, которую вы исследуете. Только когда код у вас в голове, вы действительно понимаете проблему". Новая функция основана на SWE-1.5 и Claude Sonnet 4.5, предлагая два режима работы: быстрый и интеллектуальный.

Проблема понимания кода стоит остро: новым разработчикам требуется 3-9 месяцев для полного освоения проекта, а старшие специалисты тратят более 5 часов в неделю на помощь коллегам. По данным Stripe, поддержка легаси-кода — главный фактор, снижающий продуктивность. Codemaps решает эту задачу, позволяя создавать контекстные карты кода по запросу для конкретных задач. Это следующий шаг после Ask Devin и DeepWiki, делающий процесс онбординга и навигации по кодовой базе более эффективным.

• Обсуждение в основном вращается вокруг трёх тем: визуализация кода (CodeMaps), инструментов вроде Windsurf и Cursor, а также влияние LLM на понимание и навигацию по коду.
• Участники обсуждают, насколько полезны визуализации кода в больших кодовых базах и как они справляются с контекстом и бизнес-логикой.
• Также поднимается вопрос о том, что такие инструменты могут быть полезны для онбординга в новых кодовых базах, но критики утверждают, что без контекста эти визуализации не имеют ценности.
• Некоторые участники высказывают мнение, что вместо того, чтобы полагаться на визуализации, разработчики должны уделять внимание созданию и поддержанию хорошей документации.
• Обсуждение также затрагивает влияние инструментов на продуктивность и то, как они могут быть использованы в больших и сложных кодовых базах.

• Обсуждение сосредоточено на том, что PR объемом 9000 строк кода и 63 файла невозможно ревьюить и должен быть разбит на части или отвергнуться без разбора.
• Участники подчеркивают, что такие PR нарушают базовые практики разработки и требуют автора разбить PR на меньшие, самодостаточные части.
• Сообщество подчеркивает, что такие PR часто не сопровождаются тестами или документацией, что делает невозможным проверить их корректность.
• Некоторые участники отмечают, что такие PR могут быть результатом использования AI, что вызывает дополнительные вопросы о качестве и поддержке кода.
• В конечном счете, большинство участников соглашаются, что такие PR должны быть отвергнуты с просьбой к автору разбить их на меньшие части, если это возможно, или начать с RFC или документации.

Митчелл Хашимото делится личным опытом, как не теряя мотивации довести большие проекты до конца. Он начинает с маленького, но ощутимого результата: например, вместо «сделать терминал» он берёт подпроект «распарсить VT-коды» и уже через пару дней имеет живой результат и тесты. Далее он итеративно добавляет новые фичи, каждый раз имея что-то, что можно показать. Это позволяет сохранять энтузиазм и не терять фокус. Под конец он напоминает, что не стоит стыдиться незавершённых проектов — главное, чтобы они были интересны самому автору.

• Собеседники подчеркнули, что ключ к быстрому прогрессу — это умение разбивать задачу на мелкие, легко демонстрируемые фрагменты и не застревать в «анализ-парализе»; главное — быстро получать обратную связь и не бояться «грязного» MVP.
• Подчеркнуто, что выбор инструмента (язык/стек) влияет на скорость итераций: REPL-языки и инструменты вроде hot-reload позволяют видеть эффект изменений почти мгновенно, что снижает порог входа и удерживает мотивацию.
• Участники обсуждения подтвердили: чем раньше показать работающий прототип, тем меньше вероятность, что проект застрянет в вечной «доработке»; демо-ориентированная разработка заставляет фокусироваться на ценности для пользователя, а не на перфекционизме.
• Сообщество отметило, что даже в личных проектах важно документировать и тестировать как будто ты передашь его другу: это упрощает возврат к контексту спустя месяцы и служит живым примером.
• Несколько человек поделились личным опытом, что их подход к разработке ПО вдохновил их начать вклад в open-source, и что их опыт в open-source в свою очередь улучшил их навыки ведения личных проектов.

Разработчики часто сталкиваются с тем, что официальная документация описывает функцию, но не показывает, как её использовать. Пример: вместо того, чтобы показать, как вызывать max() в Python, документация тратит абзацы на то, чтобы объяснить, что такое iterable и что значит key=. А ведь достаточно было бы показать, как передавать кастомную функцию сортировки в max().

Проект ClojureDocs берёт на себя роль «примеры — лучшая документация». Пользователи добавляют примеры к встроенным функциям, и это оказывается куда более полезным, чем формальное описание API. Примеры показывают, как вызывать функцию, какие есть подводные камни и какие есть альтернативы.

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

Pdoc автоматически генерирует API-документацию для Python-проектов, сохраняя иерархию модулей. Инструмент не требует настройки, поддерживает аннотации типов, перекрёстные ссылки и понимает docstrings в стиле Google или numpydoc. Например, команда pdoc demo.py создаст документацию для класса Dog с его атрибутами и методами, включая описание name и friends.

Pdoc также включает встроенный веб-сервер с live-перезагрузкой для удобства разработки. Он популярен среди крупных проектов, таких как Google OR-Tools и Microsoft, благодаря своей простоте и точности. Практический вывод: инструмент экономит время, автоматизируя рутинную работу по документированию.

• Участники обсуждают инструменты для генерации документации Python-библиотек, выделяя pdoc за простоту использования и автоматизацию, а MkDocs с Material-темой — для более крупных проектов с расширенными возможностями.
• Поднимаются технические нюансы, такие как размещение докстрингов для переменных (ниже объявления, по аналогии с функциями) и проверка валидности ссылок между разными системами документации.
• Обсуждается баланс между лаконичными докстрингами в коде и более подробной внешней документацией, например, с помощью Sphinx.
• Упоминаются удобство интеграции pdoc с GitHub Pages и отсутствие значительного прогресса у форков проекта.
• Затрагивается тема использования общих инструментов для проверки ссылок (например, lychee) вместо специфических библиотек для pdoc.

Typst — это новая система вёрстки документов, написанная на Rust и позиционируемая как современная альтернатива LaTeX. Она сохраняет высокое качество вывода, особенно для технических и научных материалов с формулами, таблицами и иллюстрациями, но предлагает более простой синтаксис разметки, быстрое компилирование и удобную кастомизацию. Проект развивается с 2019 года, уже насчитывает сотни контрибьюторов и постепенно получает признание в академической среде.

Ключевые преимущества Typst включают мгновенную работу со шрифтами, интерактивный режим редактирования с автоматической перекомпиляцией и поддержку современных форматов вывода. В отличие от LaTeX, он не требует гигантской установки, проще в освоении и выдаёт понятные ошибки. Хотя замена экосистемы пакетов LaTeX остаётся вызовом, Typst демонстрирует практическую ценность для тех, кто ищет лёгкий и эффективный инструмент для вёрстки.

• Пользователи отмечают значительное преимущество Typst перед LaTeX в скорости компиляции, удобстве синтаксиса и понятности диагностических сообщений.
• Многие перешли на Typst для генерации документов в продакшн-средах (инвойсы, отчёты, книги) благодаря его простоте интеграции с данными (JSON) и программируемости.
• Подчёркивается проблема принятия Typst в научном сообществе из-за доминирования LaTeX-шаблонов журналов и конференций, а также отсутствия полной поддержки инструментов вроде Zotero.
• Некоторые пользователи выражают скептицизм по поводу замены LaTeX для сложных математических формул и опасения по поводу долгосрочного развития и обратной совместимости Typst.
• Typst часто используется как замена Markdown для простых документов и заметок благодаря интуитивному формату и мгновенному предпросмотру.

Современные модели ИИ демонстрируют сверхчеловеческие способности в решении абстрактных задач, как показал недавний успех GPT-5 на ICPC, но автономные кодирующие агенты всё ещё не могут заменить разработчиков. Основное ограничение — не интеллект, а контекст: агентам не хватает глубокого понимания кодовой базы, её архитектурных паттернов и скрытых знаний, которые есть у людей.

Контекст включает не только код, но и документацию, историю решений, неформальные соглашения и причины прошлых изменений. Без доступа к Slack-тредам, постмортемам инцидентов и организационным практикам агенты работают лишь на 20% от возможного уровня, справляясь в основном с мелкими задачами. Чтобы двигаться дальше, нужны системы, способные усваивать и применять этот скрытый контекст так же, как это делают люди.

• Основным ограничением для кодирующих агентов на основе ИИ является не размер контекстного окна, а неспособность эффективно фокусироваться на актуальных задачах и отбрасывать нерелевантную информацию.
• Многие участники отмечают, что ИИ-агенты демонстрируют уровень понимания, сравнимый с начинающим разработчиком, и не способны заменить senior-специалистов, которые могут интерпретировать бизнес-требования и принимать ответственные решения.
• Существует скептицизм относительно бесконечного увеличения "интеллекта" моделей, так как даже с большим контекстом они допускают ошибки и галлюцинации, а фундаментальные ограничения вероятностной генерации остаются.
• Предлагаются решения для улучшения работы агентов: лучше структурированные кодобазы, иерархическая документация, инструменты для управления контекстом и памятью, а также человеческий контроль для курирования процесса.
• Подчёркивается, что ключевая проблема — не технический контекст, а понимание intent (намерения) стоящего за кодом, что требует более глубокого осмысления, чем простое прогнозирование токенов.

Книга Эбби Коверт предлагает системный подход к работе со сложными информационными системами. Она объясняет, что беспорядок состоит из информации и людей, и подчеркивает важность архитектуры информации, которая окружает нас повсюду. Автор утверждает, что понимание сложности пользователей, заинтересованных сторон и знаний — ключ к наведению порядка.

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

• Обсуждение подчеркивает важность инструментов визуализации, таких как диаграммы критического пути и графы зависимостей, для анализа сложных систем и процессов.
• Участники отмечают, что хаос и сложность часто возникают из-за плохой документации, низкого качества данных и взаимосвязанных проблем в системах.
• Многие комментарии критикуют дизайн сайта автора, называя его запутанным и трудным для восприятия, что отвлекает от содержания.
• Обсуждаются стратегии работы со сложностью: улучшение сигнал/шум, заимствование методик из других областей (авиация, OODA-петли) и принятие неизбежных "помоек".
• Модератор напоминает сообществу о правилах, призывая избегать непродуктивных жалоб на второстепенные раздражители, такие как формат сайтов.

Нетехнический пользователь сталкивается с типичной проблемой: туториал для начинающих написан разработчиком, который не учитывает реальный уровень новичка. Автор иронично описывает, как инструкция изобилует жаргонизмами вроде «Shoobababoo» и «Snarfus», предполагает знание скрытых системных папок и содержит запутанные команды терминала без пояснений. Ключевой момент — осознание, что даже после семи часов поисков и 193 запросов в интернете шаг «Boop!» кажется достижением, хотя суть решения остаётся непонятной. Практический вывод: обучающие материалы должны проверяться на реальной аудитории, иначе они превращаются в пародию, несмотря на благие намерения автора.

• Рекомендуется тестировать документацию на новичках или людях с минимальным опытом, наблюдая за их трудностями без помощи, чтобы выявить пробелы и неявные предположения.
• Многие руководства написаны разработчиками для других разработчиков в той же экосистеме и предполагают базовый уровень знаний, что может быть неочевидно для настоящих новичков.
• Проблема усугубляется "проклятием знания" — авторам сложно представить, что неизвестно читателю, что приводит к пропуску важных шагов, контекста и объяснения базовых концепций.
• Эффективная документация должна четко определять целевую аудиторию, предварительные требования, предоставлять конкретные примеры кода и работать в строго определенном окружении, чтобы избежать "гниения" инструкций.
• Решения включают в себя итеративную обратную связь от новых пользователей, удаление ненужного жаргона, использование интерактивных элементов и явное указание альтернатив для разных сред и инструментов.

Disciplined-AI-Software-Development
Методика структурирует совместную работу с ИИ над кодом:

• убирает раздутость,
• фиксирует архитектуру,
• сохраняет контекст.

Контрольные точки и жёсткие ограничения не дают проекту съехать в хаос.

• Пользователи спорят, стоит ли погружать Claude-Code в тонны контекста: одни делают «глубокий research-цикл» (Gemini/GPT-5 → план → агент), другие считают это медленнее ручного кода.
• Работает только жёсткий pipeline: план → ревью плана → промежуточный код-ревью → тесты/линтеры → финальное ревью; полный автомат без человека проваливается.
• LLM заставили разработчиков наконец писать документацию, но сами агенты плохо планируют и «заплывут» по мере роста кодовой базы.
• Эффективность высока лишь при маленьких, чётко заскоупленных задачах: 10-минутный спецификация → 3 часа генерации → 85 % покрытие тестами; большие коммиты всё ещё быстрее делать вручную.
• Главный риск: технология убирает бюрократию, но не переносит человеческую ответственность; ошибки агента = ошибка конкретного разработчика.

sosumi.ai — Apple-доки для ИИ
Замените developer.apple.com на sosumi.ai, и LLM получит Markdown вместо «включите JavaScript».

Пример:
https://sosumi.ai/documentation/swift/array

MCP

{ "mcpServers": { "sosumi": { "command": "npx", "args": ["-y", "mcp-remote", "https://sosumi.ai/mcp"] } } }

Ресурс: doc://swift/array
Инструмент: search(query) — поиск по документации.

Проект неофициальный, не копирует массово, кеширует 30 мин, соблюдает ToS Apple.

• Проект Sosumi.ai превращает документацию Apple в «AI-дружественный» Markdown, потому что LLM плохо читают динамически-рендерящийся HTML.
• Некоторые считают, что «AI-readable» лишнее — достаточно просто «Markdown» для людей.
• Есть просьбы: локальный архив, поддержка других сайтов, easter-egg со звуком Sosumi.
• У Apple уже есть частично похожее решение, но оно скрыто в Xcode.
• Автор обещает выложить код в open-source после приборки.

Monodraw — редактор ASCII-графики для macOS (11 Big Sur+).
Пробная версия бесплатно, лицензия — $9.99, скидки для учебных заведений.

Возможности

• Диаграммы: структуры данных, алгоритмы, ER-диаграммы (нотация «Crow’s Foot»).
• Mind-map: свободное размещение текста на бесконечном холсте.
• Баннеры: 148 встроенных шрифтов FIGlet, изменение размера и выравнивание.
• Инструменты: прямоугольники, линии (ортогональные, лестницы), текст, карандаш, ластик, заливка, пипетка.
• Точки крепления: линии автоматически цепляются к фигурам.
• CLI: генерация документации в хуках Git, экспорт JSON.
• Группы, направляющие, фокус-режим, горячие клавиши для быстрой работы.

Экспорт: PNG, SVG.

• Разработчик Monodraw отвечает на вопросы; пользователи делятся альтернативами (asciiflow, textik, durdraw, REXPaint).
• Все хвалят чистоту результата, низкую цену ($10 навсегда) и удобство вставки ASCII-диаграмм прямо в код или документацию.
• Основные сценарии: комментарии в исходниках, схемы сетей, баннеры серверов, ASCII-анимации, план кухни.
• Главный недостаток: приложение только для macOS; много просьб портировать на Linux.
• Новая текстовая разметка (апрель 2025) улучшает работу с системами контроля версий.

Разработчики тоже сталкиваются с «блоком» — аналогом писательского, но часто более тяжёлым. Причины и способы выбраться.

Почему зависаем

Новый проект
Хочется сделать «лучше всех»: покрыть тестами, написать документацию, придерживаться стиля, CI, кросс-компиляция, обработка ошибок, конкурентность… Практики полезны, но вместе превращаются в стену.

Старый проект
• Новый код — перегруз: спешишь понять, язык незнаком.
• Старый код — упал мотивация или переутомление.

Как разблокироваться

• Учись постепенно
  Запусти как пользователь, почитай тесты, спрашивай коллег. Не знаешь язык — выдели время на основы.

• Отдыхай
  После большой фичи бери «мелкие дела» или техдолг.

• Двигайся мелкими шагами
  Минимально реализуй задачу, потом улучшай тесты и доки.

• Прототипируй
  «Спайк» — быстрый черновик по happy path. Оставь в ветке, потом перепиши аккуратно.

• Документируй черновиком
  Не полируй раньше времени: простой формат, потом доведёшь.

• Сон, прогулки, спорт и медитация — лучший способ «разблокировать» мозг и получить новые идеи.
• Ранние «грязные» MVP и повторное использование boilerplate снижают страх перед чистым листом.
• LLM помогают быстро набросать черновик, преодолеть ступор и даже подсказать имена.
• Когда совсем застрял, начни писать любой код или даже инфраструктуру для отладки — движение разгоняет.
• Главное — не игнорировать сигналы тела: делай паузы, иначе выгоришь.

AGENTS.md — открытый формат инструкций для AI-агентов, используется >20k проектов.
Это «README для агентов»: единое место для команд сборки, тестов, стиля кода и прочих деталей, которые не нужны людям, но критичны для ИИ.

## Команды
- `pnpm i` — зависимости  
- `pnpm dev` — запуск  
- `pnpm test` — тесты  

## Стиль
TypeScript strict, одинарные кавычки, без точек с запятой, функциональный стиль.

Зачем отдельный файл?

• README — для людей, AGENTS.md — для агентов.
• Не загромождает документацию.
• Один формат подходит всем: Codex, Amp, Jules, Cursor, Factory, RooCode и др.

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

1. Создайте AGENTS.md в корне.
2. Добавьте: обзор проекта, команды сборки/тестов, стиль, security, правила PR.
3. В монорепозиториях кладите отдельные файлы в каждый пакет; агент читает ближайший.

Примеры

• openai/codex
• apache/airflow
• temporalio/sdk-java
• PlutoLang/Pluto

Ещё 20k примеров

• Участники спорят, нужен ли отдельный AGENTS.md или достаточно README/CONTRIBUTING.
• Одни считают файл полезной «эргономичной ручкой» — люди охотнее пишут инструкции для ИИ, чем для людей.
• Другие критикуют: это не формат, а просто соглашение; нет импортов, иерархии, стандарта между агентами.
• Практики варьируются: кто-то хранит роль-файлы в .agent, кто-то делает симлинки на CLAUDE.md, кто-то использует .agdocs/guides/.
• Общий вывод: AGENTS.md пока временный костыль, пока ИИ не научится полноценно читать человеческую документацию.

Вместо «умных» функций — просто работающие.

Везде впихивают ИИ, который никто не просил: браузеры, ОС, конференц-приложения ломаются, но деньги текут в «искусственный интеллект».
Gamescom добавил ИИ-расписание: люди получили сотни ненужных встреч, функцию быстро убрали.
Те же деньги могли бы починить DM, поиск, перенос встреч — базовые вещи, из-за которых все возвращаются к почте и LinkedIn.

Мотив один: быстрая прибыль. В итоге продукты гниют, а инвесторы кормят обещания «вот-вот будет AGI».
Один бюджет крупной компании хватило бы на 100 лет развития Godot, Blender, Ladybird — реальных инструментов, которые нужны сегодня.

Потерянные годы не вернуть.

• Участники жалуются, что вместо починки старых багов и улучшения базовых функций компании впихивают «AI-фичи», которые никому не нужны.
• Многие считают, что инвесторы сознательно выбирают технологии, которые трудно децентрализовать, чтобы сохранить контроль и монополию.
• Одни видят в нынешнем AI-хайпе очередную моду, как было с UML, блокчейном и облаками; другие – шанс на прорыв, оправдывающий «пузырь».
• Популярная идея: деньги лучше бы пошли на документацию, API и совместимость, а не на обучение моделей водить мышкой по браузеру.
• Подводный тезис – проблема не в AI, а в концентрации капитала и в том, что «зелёное поле» проще финансировать, чем ремонт «коричневого».

Разработчики всё чаще пишут документацию в специальных «контекст-папках», чтобы ИИ мог самостоятельно и точно решать задачи. Это docs-driven development: кодят меньше, пишут больше, потому что ИИ теперь обязан «RTFM».

Качество ответа LLM прямо зависит от качества входных данных. Чем больше контекстное окно, тем больше релевантной информации можно подать. Поэтому инженеры учатся писать структурированные инструкции и создавать целые библиотеки контекста.

Контент-куратор — это технический писатель, который строит стратегию знаний и для людей, и для ИИ. Контекст важнее «контента»: он ограничен, релевантен и придаёт смысл. Писатели должны владеть процессами AI-документации, включая подготовку контекста (docs-as-data).

Четыре года назад я утверждал, что писатели влияют на дизайн API словами. Теперь это распространилось на всю разработку: мы можем «вызывать» программы текстом. Большинство команд уже отдают llms.txt и Markdown для ИИ, но следующий шаг — упаковывать контекст в удобные для LLM форматы (возможно, на базе DITA). Цель — сделать знания доступными и человеку, и машине.

• AI заставляет писать больше документации — скучно, но полезно и исключает оправдания прокрастинации.
• LLM плохо справляются с новыми/обновлёнными API, часто предлагают устаревший код, если явно не указать «смотри свежие доки».
• Чтобы LLM был полезен, нужно самому понимать задачу и давать точный контекст; иначе результат неточен.
• Некоторые компании уже отдают приоритет AI-читабельным форматам (llms.txt, claude.md), но это пока редкость, а не норма.
• Хорошая документация полезна людям вне зависимости от ИИ; если ИИ подталкивает улучшать её, это плюс.

• Чёткое ТЗ — пишу заранее, чтобы агент видел контекст.
• Файл-инструкция по запуску линтервов и сборки.
• Саморевью — прошу Claude проверить свой код.
• Глобальный гайд ~/.claude/CLAUDE.md с правилами: мелкие шаги, TDD, простые решения, максимум 3 попытки при ошибке.

Качество
Я вручную читаю и тестирую всё, что выходит из LLM; отвечаю за PR независимо от автора кода.

• Ключ к успеху — писать подробные спецификации: кто-то тратит 2 часа на 12-шаговый документ и получает отличный результат, другие же считают, что даже «чистые» спеки не спасают от схода с курса и бесконечных правок.
• Мнения о CLAUDE.md разделились: одни держат файл коротким (<100 строк) и минималистичным, другие вообще не видят в нём пользы из-за «context rot» и субъективных инструкций.
• Работа с большими старыми кодовыми базами по-прежнему сложна: большинство признаёт, что Claude Code лучше справляется с новыми pet-project’ами, чем с «грязными» legacy-фичами.
• Популярные тактики: шаг-за-шагом микро-PR, TDD-агент, запуск puppeteer-тестов для «замыкания цикла», code-review собственных патчей самим агентом.
• Некоторые вообще отказались от спецификаций: инкрементально подсказывают «следующий шаг, какой сделал бы я», сразу коммитят дифф и правят на лету.

MS used to have uservoice pages. They ignored issues, no matter how highly-voted they were. I once asked someone at MS about this, and they said they take their cues from other sources, like what industry partners ask them to fix at conferences.What a waste of time to have uservo