Как написать хороший CLAUDE.md, чтобы не было мучительно больно

Когда я впервые начал всерьез работать с кодинг-агентами, казалось, что это магия: просишь поправить модуль, а через пару минут у тебя уже пулл-реквест. Но чем больше я ими пользовался, тем чаще ловил себя на одном и том же: агент то ломает билд, то игнорирует важные договоренности по архитектуре, то переписывает код "как ему удобнее". И каждый раз приходилось руками разгребать последствия "умной" автоматизации.
Со временем стало очевидно: проблема не в модели, а в том, как мы ее онбордим в проект. Один и тот же Claude в одном репозитории ведет себя как сильный мидл, а в другом как растерянный стажер. Разница почти всегда в том, что написано (или не написано) в CLAUDE.md и его аналогах для агентов.
Я перепробовал кучу подходов: от огромных "библий" с правилами до минималистичных заметок и автогенерации. Что-то работало, что-то категорически нет. В итоге вырисовались простые, но хорошо проверенные на практике принципы того, каким должен быть CLAUDE.md, чтобы не было мучительно больно ни вам, ни агенту.

















Всем привет. Меня зовут Игорь Акимов, я руководитель направления мобильных продуктов ABBYY. Наверное, многие знают