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.