agentic-docs

Write documentation that lives with the code it describes. Plain language. No jargon. Explain the why, not the what.

Co-location wins. Documentation in separate files drifts out of sync. Comments next to code stay accurate because they're updated together.

The "why" test: Before writing a comment, ask: "Does this explain why this code exists or why it works this way?" If it only restates what the code does, skip it.

Пишите четкие, понятные комментарии к коду и документацию, которая находится рядом с кодом. Используйте при написании или проверке кода, для которого требуется встроенная документация, например заголовки файлов, документация по функциям, архитектурные решения или пояснительные комментарии. Хорошо работает как для читателей-людей, так и для помощников по программированию с использованием искусственного интеллекта, которые просматривают один файл за раз. Источник: petekp/agent-skills.