Dokumentacja dla mnie i AI

Ponieważ projekt zacząłem z niewielką wiedzą i banalizowałem dokumentację mam ochotę przeprowadzić jednorazowy "eksperyment"/"proces" składający się z dwóch faz ale najpierw - przełączyć model na Fable 5 i ustawić Effort na Ultracode - xHigh + workflows

1. Faza to "Przeczytaj wszystkie pliki .md z dokumentacją, sprawdź, czy nie ma rozbieżności, błędów i czy wszystko jest spójne"
2. Faza to "Zrób szczegółowy audyt kodu i sprawdź czy zgadza się z dokumentacją"

Pliki MD nie są jakieś gigantyczne łącznie niecałe 1250 linii + sporo więcej kodu, ale muszę przyznać, że straciłem kontrolę Co mi nie przeszkadza w projekcie ale powoduje takie nieprzyjemne uczucie, że wszystko może iść szybciej i sprawniej.
Czy macie jakieś porady jak to zrobić efektywniej albo za duże ryzyko spalenia tokenów do 10 pokoleń na przód?
Może fazę pierwszą puścić na darmowym Claude?

Odpaliłem badanie dokumentów na tych ustawieniach, 10% 4-godzinnego limitu mi zjadło na badaniu 1300 linii (tak informuję jak by ktoś był ciekaw) czyli nie wiele.
Teraz odpalam pełny audyt kodu i propozycje zmian. Zaraz poinformuję.

@pradoslaw Aplikacja posiada 20k linii kodu
Po zapytaniu:
Znajdź: pokrętną, niejasną logikę, niepotrzebne fragmenty, puste funkcje, zbędny CSS.
Sprawdź: czy są ukryte mocki, śmieci w kodzie, czy wszystkie elementy są faktycznie używane.
Oceń: możliwości uproszczenia kodu, zaproponuj zmiany i ulepszenia.
Na końcu proszę o zwięzłe podsumowanie propozycji po polsku.

Zjadła 90% 4-godzinnego limitu tokenów przy planie Pro

Przy czym warto dodać w jaki sposób działam
Tworzenie, sprawdź błędy, tworzenie, sprawdź błędy i tak x razy co jakiś czas (kilka dni) "ogólny audyt" j/w

Dziś odpaliłem VS Code i widzę, że jest kontynuacja. Łącznie zjadło 2x 4 godzinne sesje ale warto było (bo znalazł rzeczy o których zapomniałem).
Między innymi:

Z ciekawości, bo nie pamiętam żebyś się dzielił, jakich narzędzi używasz? Jaki IDE (tutaj VS Code, jakiś inny?), agent (?), plany / subskrypcje?

bakunet napisał(a):

Z ciekawości, bo nie pamiętam żebyś się dzielił, jakich narzędzi używasz? Jaki IDE (tutaj VS Code, jakiś inny?), agent (?), plany / subskrypcje?

Faktycznie nie wspomniałem
Dokumentację trzymam w plikach MD a Claude posiłkuje się historią commi-tów
Win11 64, VS Code 1.128, Plan PRO, GitHub, Rust, JS
wszelkie pozostałe ustawienia Auto/Domyślne
Jedyną rzeczą którą postanowiłem zmienić to przełączyć model na "Fable 5" i ustawić Effort na "Ultracode - xHigh + workflows"

Bardzo użyteczna porada Każdy projekt, nawet taki który wydaje się banalny z wierzchu a w przyszłości potencjalnie ma otrzymać upgrade-y, bez dokumentacji może stać się króliczą norą szczególnie dla vibecodera.

Na czym polega taka dokumentacja dla AI? To brzmi dość abstrakcyjnie

bakunet napisał(a):

Na czym polega taka dokumentacja dla AI? To brzmi dość abstrakcyjnie

Bardzo dobre pytanie and którym właśnie rozmyślam "optymalizacja dokumentacji" w kontekście projektu który jej wcześniej praktycznie nie posiadał.
Nie jestem jakimś wyznacznikiem w tym temacie ale z doświadczenia, AI używa sformułowań dla mnie nie zawsze czytelnych.

IMHO (użytkownika który nie zagląda do kodu, czyli czysty vibecoding)

W skrócie dokumentacje:

• dla AI to instrukcje dla współautora
• dla użytkownika to instrukcje dla odbiorcy.

Różnica:
Dokumentacja dla AI
opisuje jak projekt działa od środka
zawiera instrukcje, konwencje, zasady, architekturę
jest techniczna, precyzyjna, często skrótowa w nomenklaturze programistycznej
AI używa jej do generowania kodu, testów, zmian, roadmapy
musi być spójna i aktualna
co najważniejsze szybko przywraca kontekst i pozwala zaoszczędzić tokeny

Dokumentacja dla użytkownika:
opisuje jak korzystać z projektu
jest prostsza, bardziej narracyjna
trafia do README, Wiki, stron projektu
może być mniej szczegółowa
nie musi odzwierciedlać pełnej architektury

Te dwie dokumentacje mogą się rozjeżdżać, bo mają różne cele.

Tu są przykładowe faktyczne różnice:
Struktura plików i folderów (Claude‑friendly/GH community standards)
(wiem, że pasek community standards, pewnie nikogo nie obchodzi ale osobiście wolę jak jest wszystko zgodnie ze standardami :) )
GH woli jak plik README I CONTRIBUTING są w root
Claude woli mieć wszystko w /docs
Z czego wnioskuję że README.md powinien być czytelny dla użytkownika i dla Claude jednocześnie.

Co zmieni, gdy dokumentację będę miał w innym folderze lub w plikach o innej nazwie?
Językiem natywnym dla Claude jest angielski. Nie, żeby był to jakiś problem dla mnie a właściwie to chyba i tak przerzucę się na angielski.

Wnioskuję, że trzymanie się standardów przy dużych projektach jest bardziej "token efficient"

chętnie sam zweryfikuję swoją wiedzę bo "optymalizacja dokumentacji" brzmi trochę absurdalnie

Ciekaw jestem czy ta dokumentacja dla AI to komentarze w kodzie, czy pliki konfiguracyjne a komentarze to dla użytkownika?

bakunet napisał(a):

Ciekaw jestem czy ta dokumentacja dla AI to komentarze w kodzie, czy pliki konfiguracyjne a komentarze to dla użytkownika?

Na chwilę obecną możesz podejrzeć dokumentację jednego z projektów, która wymknęła się trochę spod mojej kontroli
https://github.com/michalstankiewicz4-cell/IPscanner/tree/main/docs
To jest chyba to co ciebie interesuje -> https://github.com/michalstankiewicz4-cell/IPscanner/blob/main/CONTRIBUTING.md

Jedyny plik który sam stworzyłem i na ten czas ogarniam to
https://github.com/michalstankiewicz4-cell/IPscanner/blob/main/README.md
https://github.com/michalstankiewicz4-cell/IPscanner/blob/main/docs/SHELL_PROGRESS.md

Resztę dopiero analizuję