Sam kod nie opowiada całej historii. Aby naprawdę zrozumieć projekt, asystent AI potrzebuje dostępu do tej samej dokumentacji, którą używałby człowiek-programista: referencji API, diagramów architektonicznych, wymagań produktowych i przewodników stylu. Traktowanie dokumentacji jako pierwszoklasowego źródła kontekstu to supermoc dla rozwoju wspomaganego przez AI.
Ten przewodnik bada, jak skutecznie używać zarówno wewnętrznej jak i zewnętrznej dokumentacji do kierowania partnerem AI.
Używanie dokumentacji z asystentem AI tworzy potężną pętlę sprzężenia zwrotnego:
Dokumenty jako wejście: Dostarczasz istniejącą dokumentację (np. PRD, referencję API biblioteki) jako kontekst dla zadania kodowania.
AI generuje kod: AI używa dokumentacji do generowania kodu zgodnego z wymaganiami projektu i zewnętrznymi zależnościami.
AI generuje dokumenty: Następnie prosisz AI o wygenerowanie lub aktualizację dokumentacji dla nowego kodu, który właśnie napisał (np. tworzenie README.md lub dodawanie komentarzy JSDoc).
Nowe dokumenty jako wejście: Ta nowo wygenerowana dokumentacja staje się źródłem kontekstu dla następnego zadania programistycznego.
Integrując AI w przepływ pracy dokumentacji, zapewniasz, że dokumentacja pozostaje aktualna i ciągle służy jako dokładne źródło prawdy zarówno dla ludzkich jak i AI programistów.
To wiedza specyficzna dla projektu i organizacji. To najkrytyczniejszy kontekst, ponieważ AI nie ma innego sposobu na jej poznanie.
PRD i specyfikacje: Trzymaj je w repozytorium (/docs/prd.md) i odwołuj się do nich przez @.
Zapisy decyzji architektonicznych (ADR): Wyjaśniają dlaczego stojące za wyborami technicznymi.
Pliki README: Umieszczaj pliki README.md wraz ze złożonymi modułami, aby zapewnić szybki przegląd.
Przewodniki stylu: Skodyfikuj konwencje zespołu w dokumencie, do którego AI może się odwoływać.
Dokumentacja zewnętrzna
Dokumentacja frameworków i bibliotek zapewnia zasady interakcji z kodem zewnętrznym. Modele mają datę odcięcia wiedzy, więc dostarczenie aktualnej dokumentacji jest kluczowe.
@Docs Cursor: Użyj @Docs do pobrania oficjalnej, aktualnej dokumentacji dla popularnych bibliotek i frameworków.
@Web Cursor: Dla bardzo świeżych lub społecznościowych informacji (jak posty na blogach czy issues na GitHub) użyj @Web do wykonania wyszukiwania na żywo.
Ręczne wklejanie: Zawsze możesz skopiować i wkleić URL lub tekst z dowolnego źródła dokumentacji bezpośrednio do czatu.
Gdy zaczynasz pracę nad nowym projektem, pierwszym krokiem jest często przeczytanie dokumentacji. To samo dotyczy asystenta AI. Przed rozpoczęciem złożonego zadania możesz przygotować AI, prosząc go:
Podsumuj kluczowe wzorce architektoniczne opisane w @/docs/architecture.md i główne przepływy użytkownika z @/docs/prd.md.
To buduje wspólne zrozumienie i zapewnia, że późniejsza praca AI jest zgodna z podstawowymi zasadami projektu.
Zamiast ręcznego tłumaczenia dokumentu wymagań produktowych na kod, pozwól AI wykonać ciężką pracę.
Zaimplementuj funkcję "Profil użytkownika V2" zgodnie z opisem w @/docs/prd.md#user-profile-v2. Zwróć szczególną uwagę na kryteria akceptacji. Użyj istniejących komponentów w @/src/components/profile/.
Odwołując się do PRD i istniejącego kodu, dostarczasz zarówno kontekst intencji (co zbudować) jak i kontekst stanu (z czym to zbudować).
