FEAT | AI code review clean code

[pekral]

Uprav CR skilly tak, aby:

Smažte dokumentaci, kterou vytvoříte k vysvětlení svého kódu
Vynucjte je na to, aby byl váš kód sám o sobě srozumitelný
Jedinou výjimkou jsou věci, které kód sám o sobě nedokáže vysvětlit, jako například zvažované alternativy nebo doménový jazyk. Tedy ADR a glosáře.
Další výjimkou jsou navigační ukazatele – tenké řetězce odkazů, které tvoří „cesty“, kterými se AI pohybuje v vašem zdrojovém kódu.

[pekral]

Hotovo — souhrn změn (PR #735)

Autoři: Petr Král (@pekral)

Shrnutí změn:
Code review nově prochází novou kontrolu Self-Documenting Code — Comment & Doc Hygiene. Při každém review se u komentářů a dokumentace, které diff přidává nebo mění, hlídá, aby komentáře jen neopakovaly, co už kód sám říká (takové se navrhne smazat — kód má být srozumitelný sám o sobě). Dvě věci se nikdy nemažou: (1) vysvětlení proč — zvažované alternativy, rozhodovací rationale a doménový jazyk, které patří do ADR a glosářů; (2) navigační ukazatele — tenké odkazy typu @rules/…, @skills/… nebo odkazy na spolupracující třídy/metody, kterými se člověk i AI pohybuje ve zdrojáku. Tato kontrola je pouze na úrovni Minor (čitelnost/šum) a sama o sobě nikdy neblokuje merge.

Kde je to k dispozici: Automaticky při každém code review — není potřeba nic zapínat.

Jak otestovat:

1. Spusťte code review nad diffem, který přidává komentář jen popisující, co kód dělá (např. // increment counter nad $counter++) — review ho označí jako Minor s návrhem smazat.
2. Ověřte, že komentář vysvětlující proč (rationale / doménový termín) ani navigační odkaz (@rules/…, „see Trida::metoda()") review neoznačí.

Poznámka k CR: kvalita/architektura 0 nálezů, security review 0 Critical / 0 Moderate / 1 Minor (volitelný hardening). Konvergováno.

[pekral]

Authors: @pekral

Summary of changes

Hotovo — co se změnilo a jak otestovat

AI code review nově vynucuje self-documenting kód: přibyl nový kontrolní bod (lens) „Self-Documenting Code — Comment & Doc Hygiene", který při každé revizi kódu (code-review a jeho GitHub/JIRA/Bugsnag varianty) hlídá komentáře a dokumentaci přidané nebo změněné v diffu. Pokud komentář jen opakuje, co kód už sám říká (např. // increment counter nad $counter++), review na to upozorní jako na drobný (Minor) nález s návrhem komentář smazat — čtenář by měl porozumět kódu bez něj. Ze škrtání jsou ale záměrně vyňaty dva typy poznámek, které kód sám vyjádřit neumí: (1) vysvětlení proč — zvažované alternativy, důvody rozhodnutí, doménové pojmy, které patří do ADR dokumentů a glosářů, a (2) navigační odkazy (@rules/…, @skills/…, „viz Třída::metoda"), které pomáhají najít cestu ke kódu. Změna se týká pouze pravidel a textu code-review nástroje, žádného aplikačního kódu ani chování běžícího systému.

How to test

1. Otevři rules/code-review/general.mdc a ověř, že obsahuje novou sekci „Self-Documenting Code — Comment & Doc Hygiene Analysis" s oběma výjimkami (znalost, kterou kód nevyjádří → ADR/glosáře; navigační ukazatele) výslovně označenými jako „nikdy nemazat".
2. Spusť code review nad diffem, který přidává komentář jen opakující kód (např. // increment counter nad $counter++, nebo @param int $id The id) — očekávej drobný (Minor) nález s návrhem komentář smazat.
3. Spusť code review nad diffem, který přidává komentář vysvětlující proč (zvažovaná alternativa, důvod workaroundu) nebo doménový pojem patřící do glosáře — ověř, že komentář není nahlášen.
4. Spusť code review nad diffem, který přidává navigační odkaz (@rules/…, @skills/…, „viz Třída::metoda") — ověř, že odkaz není nahlášen.
5. Ověř, že skills/code-review/SKILL.md jmenuje nový kontrolní bod v seznamu Core Analysis a že skill zůstává v limitu (kontrola composer skill-check prochází zeleně).
6. Spusť celou testovací sadu (composer build) — všech 326 testů včetně nového testu pro tento lens (issue FEAT | AI code review clean code #733) musí projít, s pokrytím na 100 %.