1-comments — правило для Claude Code и Cursor: комментарии без ссылок
Правило 1-comments для ИИ-агента: писать комментарий только там, где молчат код и имена, и не ссылаться на тикеты, PR и даты.
MIT ★ 571 обновлён 2026-10-29
.claude/rules/1-comments.mdЧто делает 1-comments
Правило срабатывает, когда агент пишет новый комментарий или решает, оставить ли старый. Пересказ следующей строки — повод удалить. История правки тоже. Остаётся то, чего не говорят код и имена: ограничение, которое не выразить типом, замеренная странность хоста, отвергнутая простая форма решения.
Внутри файла есть список paths — src/**/*.ts, tests/**/*.ts, scripts/**. За их пределами правило молчит. Комментарий занимает одну-две строки, длинное объяснение уходит в aidd_docs/memory/. В репозитории фреймворка tests/architecture/comments.arch.test.ts отбраковывает внешние ссылки и постепенно снижает допустимый объём.
Ссылку на тикет или PR правило запрещает прямо, так что привычный комментарий со ссылкой на задачу придётся переписать или выбросить. Без теста в своём проекте двухстрочный лимит держится на том, кто смотрит диф.
Какие задачи решает
- убрать комментарии, которые пересказывают следующую строку
- заменить ссылку на тикет описанием самого ограничения
- сократить объяснение до двух строк и унести остальное в
aidd_docs/memory/ - записать замеренную странность хоста, которую не видно из типов
- остановить рост объёма комментариев в проекте
Примеры запросов агенту
- Пройди по
src/**/*.tsи удали комментарии, которые повторяют код или рассказывают историю правки. - Оставь в этом файле только комментарии, где есть факт и его следствие, остальное убери.
- Проверь диф на ссылки на тикеты, PR и URL внутри комментариев и перепиши их без ссылок.
Как установить 1-comments
Вручную: положить файлы
.claude/rules/1-comments.mdПоле paths во frontmatter ограничивает файлы
AGENTS.md
Codex читает AGENTS.md: вставьте текст правила туда
Вручную: положить файлы
.cursor/rules/1-comments.mdcВо frontmatter: description, globs, alwaysApply
Вручную: положить файлы
.github/instructions/1-comments.instructions.mdПоле applyTo задаёт, к каким файлам применять
Вручную: положить файлы
.devin/rules/1-comments.mdВручную: положить файлы
.clinerules/1-comments.mdПо шагам, с командами для каждой платформы: AGENTS.md и CLAUDE.md: что это, кто читает и какой выбрать
Вопросы о 1-comments
Как установить 1-comments в Claude Code?
Создай в проекте файл .claude/rules/1-comments.md и вставь в него текст правила.
Что делает 1-comments?
Задаёт агенту рамки для комментариев: оставлять факт и его следствие, не пересказывать код и не ссылаться на тикеты, PR, коммиты, даты, ревью и URL.
На какие файлы действует правило?
Список paths ограничивает его каталогами src/**/*.ts, tests/**/*.ts и scripts/**. В остальных файлах агент на него не опирается.
Исходный текст
1-comments.md · MIT
--- description: Apply when writing or keeping a comment; a comment says what the code cannot, and names no external reference. paths: - "src/**/*.ts" - "tests/**/*.ts" - "scripts/**" --- # Comments - Comment only what code and names cannot say. - Worth one: a constraint types miss, a measured host quirk, a refused simpler shape. - Delete a comment that restates code or narrates history. - Name no ticket, PR, commit, date, review or URL. - Keep the fact and its consequence. - One or two lines; a paragraph belongs in `aidd_docs/memory/`. - `tests/architecture/comments.arch.test.ts` refuses external references and ratchets volume down.
© ai-driven-dev · MIT · ai-driven-dev/framework