Tworzenie szczegółowego planu technicznego

  • 12 minut

Specyfikacja definiuje, co należy skompilować. Plan techniczny definiuje sposób jego tworzenia. Jednostka obejmuje zaawansowane techniki planowania dla scenariuszy brownfield w przedsiębiorstwach.

Przegląd podstawowych elementów planu

Plik plan.md służy jako dokument projektowy, pomostując lukę między wymaganiami wysokiego poziomu w spec.md a konkretnymi zadaniami implementacji, które następują. Kompleksowy plan techniczny zawiera:

  • Omówienie architektury: ogólny widok interakcji składników.
  • Stos technologii i kluczowe decyzje: jawna dokumentacja wyborów technologicznych z uzasadnieniem.
  • Sekwencja implementacji: logiczny postęp kroków implementacji.
  • Weryfikacja konstytucji: Jawne sprawdzenie, czy proponowane rozwiązania są zgodne z zasadami projektu.
  • Założenia i otwarte pytania: Dokumentacja założeń i nierozwiązanych pytań.

Mając na uwadze te podstawy, przyjrzyjmy się zaawansowanym aspektom planowania rozwoju przedsiębiorstwa.

Separacja zagadnień — specyfikacja a plan

Rozdzielenie kwestii między specyfikacją a planem technicznym ma kluczowe znaczenie. Chociaż specyfikacja pozostaje stabilna i koncentruje się na "tym, co", plan może ewoluować w miarę eksperymentów z różnymi podejściami "jak".

Załóżmy, że specyfikacja wymaga funkcji przekazywania dokumentów dla wewnętrznego portalu pracowników. Specyfikacja definiuje wymagania użytkownika: limity rozmiaru plików, obsługiwane formaty, przekazywanie opinii i kontrole dostępu. Plan techniczny przekłada te wymagania na konkretne decyzje dotyczące architektury: której usługi Azure Storage użyć, sposobu struktury interfejsu API, mechanizmu uwierzytelniania do zaimplementowania i sposobu weryfikowania plików. Jeśli zdecydujesz się przełączyć się z jednej technologii na inną, na przykład z usługi Azure Blob Storage do usługi Azure Files, zaktualizujesz plan.md, podczas gdy spec.md pozostanie w dużej mierze niezmieniona. Wymagania dotyczące funkcji nie są zmieniane; zmienia się tylko podejście implementacji.

Badanie struktury i zawartości planu

Kompleksowy plan techniczny zawiera kilka kluczowych sekcji, które wspólnie definiują podejście implementacji.

Przegląd architektury

Omówienie architektury zawiera ogólny widok interakcji składników. W przypadku funkcji przekazywania dokumentu architektura może opisywać następujące elementy:

Zaimplementuj nowy punkt końcowy interfejsu backend API /api/documents/upload do obsługi wysyłania plików w wielu częściach. Fronton React zawiera nowy składnik DocumentUpload z selektorem plików i wskaźnikiem postępu. Gdy użytkownik wybierze plik, interfejs użytkownika weryfikuje rozmiar i typ przed przesłaniem. Zaplecze odbiera plik, weryfikuje go ponownie, przechowuje w usłudze Azure Blob Storage i rejestruje metadane w bazie danych SQL. Po pomyślnym przekazaniu pliku, interfejs użytkownika odświeża listę dokumentów, aby wyświetlić nowy plik.

To podsumowanie określa ogólny przepływ bez przechodzenia do szczegółów na poziomie kodu. Zapewnia to wszystkim zrozumienie głównych składników i ich interakcji.

Stos technologii i kluczowe decyzje

Plan jawnie dokumentuje wybory technologiczne i uzasadnienie. Ta sekcja zapobiega przyszłym nieporozumieniom dotyczącym tego, dlaczego wybrano określone biblioteki lub usługi.

Przykładowe decyzje technologiczne:

  • Zaplecze: internetowy interfejs API platformy .NET 8 z pakietem SDK Azure.Storage.Blobs w wersji 12 dla operacji blob.
  • Front end: React 18 z komponentem Upload Ant Design dla spójności interfejsu użytkownika.
  • Uwierzytelnianie: użyj istniejącego tokenu identyfikatora Entra firmy Microsoft z kontekstu uwierzytelniania portalu.
  • Storage: kontener usługi Azure Blob Storage o nazwie employee-documents.
  • Baza danych: rozszerz istniejącą bazę danych SQL za pomocą tabeli DocumentMetadata (kolumny: Id, UserId, FileName, BlobUrl, UploadDate, FileSize).

Każda decyzja powinna być zgodna zarówno z wymaganiami specyfikacji, jak i zasadami konstytucji. Jeśli konstytucja nakazuje "Korzystanie z usług platformy Azure dla wszystkich zasobów w chmurze", plan jawnie wybiera usługę Azure Blob Storage i odwołuje się do tej zasady.

Sekwencja implementacji

Plan przedstawia kolejność kroków implementacji. Chociaż nie jest tak szczegółowa, jak lista zadań wygenerowana później, ta sekwencja zapewnia logiczny postęp od konfiguracji do ukończenia.

Typowa sekwencja implementacji funkcji przekazywania dokumentu:

  1. Aktualizacja schematu bazy danych: utwórz tabelę DocumentMetadata z odpowiednimi indeksami i ograniczeniami.
  2. Tworzenie interfejsu API zaplecza: zaimplementuj punkt końcowy POST /api/documents/upload z walidacją plików, integracją magazynu obiektów blob i utrwalaniem metadanych.
  3. Tworzenie składnika interfejsu użytkownika: budowanie składnika DocumentUpload z możliwością wyboru plików, walidacją po stronie klienta i wyświetlaniem postępu przesyłania.
  4. Integracja: Podłącz komponent front-end do interfejsu API zaplecza, obsługuj odpowiedzi i aktualizuj listę dokumentów.
  5. Wzmacnianie zabezpieczeń: zaimplementuj walidację typu pliku po stronie serwera, limity rozmiaru i kontrole uwierzytelniania.
  6. Obsługa błędów: Dodaj kompleksowe komunikaty o błędach dla błędów po stronie klienta i serwera.
  7. Testowanie: Utwórz testy jednostkowe dla metod interfejsu API i testy integracyjne dla przepływu przekazywania.

Ta sekwencja gwarantuje, że podstawowe elementy (schemat bazy danych) istnieją przed zaimplementowaniem składników zależnych (interfejsu API, który zapisuje dane do bazy danych). Każdy krok opiera się na poprzedniej pracy, zmniejszając prawdopodobieństwo problemów z integracją.

Weryfikacja konstytucji

Plan zawiera sekcję weryfikacji, która jawnie sprawdza proponowane rozwiązania przeciwko konstytucji. Ta weryfikacja zapobiega dryfowi architektury i zapewnia spójność z zasadami projektu.

Jeśli konstytucja zawiera "Wszystkie magazyny danych muszą korzystać z usług platformy Azure" i "Interfejsy API muszą weryfikować dane wejściowe zarówno na kliencie, jak i serwerze", sekcja weryfikacji planu potwierdza:

  • "Korzystanie z usługi Azure Blob Storage spełnia wymagania dotyczące usług platformy Azure".
  • Implementacja walidacji zarówno w komponencie React (po stronie klienta), jak i w API .NET (po stronie serwera) jest zgodna z zasadą bezpieczeństwa warstwowego.
  • "Wymaganie uwierzytelniania identyfikatora Entra firmy Microsoft jest spełnione przy użyciu istniejącego kontekstu uwierzytelniania portalu".

Ta weryfikacja służy jako punkt kontrolny. Jeśli plan proponuje coś, co narusza konstytucję, sztuczna inteligencja zwykle flaguje ją lub zauważasz podczas przeglądu. Rozwiązywanie konfliktów konstytucji w fazie planowania uniemożliwia późniejsze przeróbki.

Założenia i otwarte pytania

Dobrze skonstruowane plany dokumentują założenia i nierozwiązane pytania. Ta przejrzystość pomaga zidentyfikować potencjalne problemy przed rozpoczęciem implementacji.

Przykładowe założenia:

  • "Załóżmy, że kontener usługi Azure Blob Storage "employee-documents" istnieje i jest skonfigurowany pod kątem dostępu prywatnego.
  • "Załóżmy, że istniejąca baza danych SQL ma wystarczającą pojemność magazynu dla metadanych".
  • "Przyjmij, że skanowanie wirusów przekazanych plików jest poza zakresem tej iteracji"."

Przykładowe otwarte pytania:

  • "Czy administratorzy powinni mieć możliwość usunięcia przekazanych dokumentów innych użytkowników?"
  • "Czy potrzebujemy rejestrowania inspekcji dla wszystkich prób dostępu do dokumentów?"
  • "Czy system powinien wysyłać powiadomienia e-mail po przekazaniu dokumentów?"

Dokumentowanie tych założeń i pytań zapobiega pełzaniu zakresu i zapewnia uczestnikom projektu rozwiązanie ważnych decyzji przed rozpoczęciem kodowania. Jeśli założenie okaże się nieprawidłowe podczas implementacji, możesz odpowiednio zaktualizować plan.

Generowanie planu przy użyciu /speckit.plan

Zestaw GitHub Spec Kit generuje plany za pomocą polecenia /speckit.plan w usłudze GitHub Copilot Chat. To polecenie używa zarówno spec.md, jak i constitution.md jako danych wejściowych w celu utworzenia kompleksowego projektu technicznego.

Przed wywołaniem polecenia zastanów się, jakiego kontekstu potrzebuje sztuczna inteligencja. Istniejąca baza kodu, preferencje technologiczne i ograniczenia infrastruktury wpływają na plan. Podanie tego kontekstu z góry daje dokładniejsze i bardziej użyteczne wyniki.

W przypadku funkcji przekazywania dokumentu w wewnętrznym scenariuszu portalu pracowników możesz podać kontekst podobny do następującego:

"Istniejący portal używa frontonu React z zapleczem internetowego interfejsu API platformy .NET 8. Musimy zintegrować funkcję przesyłania z tym stosem. Użyj usługi Azure Blob Storage do utrwalania plików. Wymagaj uwierzytelniania Microsoft Entra ID dla wszystkich operacji przesyłania. Portal ma już bazę danych SQL dostępną dla magazynu metadanych.

Ten kontekst wskazuje sztucznej inteligencji, jak wygenerować plan, który bezproblemowo pasuje do waszej istniejącej architektury, zamiast proponować rozwiązanie typu greenfield, które nie jest zgodne z waszym bieżącym stosem.

Wywołaj polecenie planowania

Otwórz aplikację GitHub Copilot Chat w programie Visual Studio Code i wprowadź polecenie /speckit.plan. Jeśli sztuczna inteligencja żąda dodatkowych informacji, podaj kontekst architektury. GitHub Copilot przetwarza specyfikację, strukturę i dodatkowy kontekst, aby wygenerować plan.md.

Faza planowania może zająć chwilę, ponieważ sztuczna inteligencja uwzględnia różne podejścia, sprawdza je z Twoimi wytycznymi i układa dane wyjściowe w spójny dokument projektowy.

Przeglądanie i weryfikowanie planu

Generowanie planu jest tylko pierwszym krokiem. Przegląd krytyczny zapewnia, że plan jest dokładny, kompletny i zgodny z potrzebami projektu.

Weryfikowanie zakresu wymagań specyfikacji

Porównaj plan z spec.md systematycznie. Każde wymaganie zawarte w specyfikacji powinno odpowiadać podejściu do implementacji w planie.

Jeśli na przykład spec.md wymaga „wyświetlania komunikatu o błędzie dla plików przekraczających 50 MB”, plan powinien opisać, gdzie i w jaki sposób odbywa się ta walidacja. Jeśli plan pomija tę walidację, plan jest niekompletny lub specyfikacja wymaga wyjaśnienia.

Sprawdzanie zgodności ze standardami technicznymi

Upewnij się, że opcje technologii planu są zgodne ze standardami i najlepszymi rozwiązaniami organizacji. Jeśli twój zespół standandalizuje określone biblioteki lub wzorce, plan powinien odzwierciedlać te preferencje.

Pytania do rozważenia:

  • Czy proponowana architektura pasuje do istniejących systemów?
  • Czy wybrane biblioteki są zatwierdzone do użycia w danym środowisku?
  • Czy wybory technologiczne są zgodne z zasadami zabezpieczeń i zgodności organizacji?
  • Czy istnieją ustalone wzorce dla podobnych funkcji, które należy przestrzegać?

W przypadku funkcji przekazywania dokumentów w środowisku platformy Azure sprawdź, czy usługa Azure Blob Storage jest zatwierdzoną usługą, czy podejście uwierzytelniania jest zgodne ze standardami tożsamości przedsiębiorstwa (takimi jak używanie identyfikatora Microsoft Entra ID) i czy proponowany schemat SQL jest zgodny z konwencjami nazewnictwa baz danych.

Weryfikowanie zgodności konstytucji

Plan powinien obejmować jawną weryfikację, że proponowane rozwiązania są zgodne z wymaganiami konstytucji. Uważnie przejrzyj tę sekcję weryfikacji, aby upewnić się, że żadne zasady nie zostały naruszone.

Jeśli konstytucja wymaga "Wszystkie wpisy tajne muszą być przechowywane w usłudze Azure Key Vault", a plan proponuje przechowywanie parametrów połączenia usługi Azure Storage w appsettings.json, istnieje konflikt. Plan powinien zostać zmieniony w celu pobrania parametrów połączenia z usługi Key Vault w czasie wykonywania.

Naruszenia konstytucji odkryte podczas planowania są łatwe do naprawienia. Naruszenia konstytucji wykryte podczas przeglądu kodu lub wdrażania produkcyjnego są kosztowne i destrukcyjne.

Iterowanie i uściślinie planu

Plany często wymagają doprecyzowania po ich początkowym sporządzeniu. Nie oczekuj perfekcji podczas pierwszej próby. Skorzystaj z możliwości wyjaśnienia narzędzia GitHub Copilot, aby poprawić jakość planu.

Rozwiązywanie niejednoznaczności i luk

Jeśli plan zawiera niejasne instrukcje, takie jak "implementowanie odpowiedniej obsługi błędów", naciśnij , aby uzyskać szczegółowe informacje. Jakie błędy mogą wystąpić? Jak należy obsłużyć każdy błąd? Jakie informacje o błędzie powinny być rejestrowane w porównaniu z wyświetlanymi użytkownikom?

Użyj funkcji GitHub Copilot Chat, aby zadawać pytania uzupełniające: "Jakie konkretne błędy powinny być obsługiwane przez punkt końcowy przesyłania?" lub "Co się stanie, jeśli Azure Blob Storage jest niedostępne?" AI może rozszerzać niejasne sekcje na konkretne specyfikacje.

Weryfikowanie możliwości technicznych

Sprawdź, czy proponowana architektura jest technicznie wykonalna, biorąc pod uwagę ograniczenia. Jeśli plan proponuje przekazywanie 50 MB plików synchronicznie za pośrednictwem internetowego interfejsu API z 30-sekundowym limitem czasu, istnieje problem. Pliki większe niż 50 MB mogą wymagać przesyłania w częściach lub wydłużenia czasu oczekiwania.

Skontaktuj się z członkami zespołu, którzy mają odpowiednią wiedzę. Jeśli plan proponuje zmiany schematu bazy danych, zapoznaj się z administratorem bazy danych. Jeśli proces wymaga nowych zasobów platformy Azure, sprawdź z inżynierami infrastruktury, czy możliwe jest ich dostarczenie.

Weź pod uwagę wymagania niefunkcjonalne

Upewnij się, że plan spełnia wymagania niefunkcjonalne ze specyfikacji: wydajność, zabezpieczenia, skalowalność, łatwość konserwacji, dostępność.

W przypadku przekazywania dokumentów upewnij się, że plan obejmuje następujące elementy:

  • Wydajność: Jak szybko należy ukończyć przekazywanie? Jaki jest maksymalny współbieżny wolumin przekazywania?
  • Zabezpieczenia: W jaki sposób pliki są skanowane pod kątem złośliwego oprogramowania? Jak jest kontrolowany dostęp? Gdzie są przechowywane dzienniki inspekcji?
  • Skalowalność: Jak system obsługuje zwiększony wolumin przekazywania? Co to są limity pojemności magazynu?
  • Łatwość konserwacji: W jaki sposób przesyłane pliki są czyszczone, gdy pracownicy opuszczają organizację?
  • Ułatwienia dostępu: Czy interfejs użytkownika przesyłania spełnia standardy ułatwień dostępu do zawartości internetowej (WCAG) 2.1 AA?

Jeśli plan pomija którykolwiek z tych zagadnień, dodaj je jawnie. Wymagania niefunkcjonalne często stają się kwestią drugorzędną podczas wdrażania, jeśli nie są uwzględniane w planowaniu.

Ocena możliwości i kompletności

Oceń, czy plan zawiera wystarczające wskazówki dotyczące implementacji. Plany, które są zbyt niejasne ("Implementowanie przekazywania plików") nie są przydatne. Plany, które są zbyt nakazowe ("Użyj dokładnie 47 wierszy kodu") są zbyt ograniczone.

Odpowiedni poziom szczegółowości zapewnia jasny kierunek bez usuwania całej elastyczności. Plan powinien odpowiedzieć:

  • Jakie składniki należy utworzyć lub zmodyfikować?
  • W jaki sposób te składniki współdziałają?
  • Jakie technologie i biblioteki są używane?
  • Jaka jest kolejność implementacji?
  • Jakie kroki weryfikacji zapewniają poprawność?

Jeśli nie możesz wyobrazić sobie, jak zaimplementować funkcję z planu, potrzebuje więcej szczegółów. Jeśli plan wygląda tak, jakby pisać kod dla Ciebie, może to być zbyt szczegółowe.

Identyfikowanie brakujących elementów

Poszukaj luk w planie. Typowe pominięcia obejmują:

  • Obsługa błędów: Jak system obsługuje błędy sieci, błędy magazynu lub problemy z bazą danych?
  • Zagadnienia dotyczące wydajności: czy istnieją jakieś obawy dotyczące szybkości przekazywania, współbieżnych użytkowników lub limitów magazynu?
  • Strategia testowania: Jakie testy należy napisać, aby zweryfikować implementację?
  • Podejście do wycofywania: Jeśli wdrożenie powoduje problemy, jak przywracasz zmiany?

Rozwiąż te luki, ręcznie edytując plan.md lub udostępniając więcej kontekstu i ponownie tworząc odpowiednie sekcje.

Ponowne generowanie przy użyciu uściśliowanego kontekstu

Jeśli początkowy plan nie spełnia oczekiwań, przedstaw bardziej szczegółowy kontekst i wygeneruj plan ponownie. Jeśli na przykład plan sugeruje użycie nowej bazy danych, ale musisz użyć istniejącej, wyjaśnij: "Użyj istniejącej bazy danych EmployeePortal. Dodaj tabelę DocumentMetadata do tej bazy danych, zamiast tworzyć nowe.

Wygeneruj ponownie plan z /speckit.plan uwzględniając ten zaktualizowany kontekst. Sztuczna inteligencja odpowiednio dostosowuje podejście.

Ręczne edytowanie planu

Ponieważ plan.md jest plikiem Markdown, można go edytować bezpośrednio. Jeśli sztuczna inteligencja sugeruje podejście o wartości 90% poprawne, ale wymaga drobnych korekt, zmodyfikuj plik zamiast ponownie wygenerować wszystko.

Jeśli na przykład plan proponuje określoną nazwę kontenera typu blob, ale organizacja ma konwencje nazewnictwa, zaktualizuj nazwę kontenera bezpośrednio w plan.md.

Współpraca z członkami zespołu

W środowiskach zespołowych udostępnij plan.md do przeglądu. Starszy deweloper lub architekt może zweryfikować decyzje dotyczące architektury przed rozpoczęciem implementacji. Ten przegląd koleżeński wychwyca problemy, które automatyczne kontrole mogą przeoczyć.

Przegląd zespołowy również tworzy wspólne zrozumienie. Gdy wielu deweloperów pracuje nad funkcją, przeglądanie planu razem zapewnia, że wszyscy znają podejście i mogą identyfikować potencjalne konflikty z innymi trwającymi pracami.

Dokumentowanie decyzji dotyczących architektury

Plany powinny dokumentować nie tylko to, co utworzysz, ale dlaczego dokonano konkretnych wyborów architektonicznych, aby ułatwić przyszłym deweloperom zrozumienie kontekstu decyzyjnego.

Rozważane alternatywy rekordów

Jeśli wybierasz między wieloma realnymi podejściami, zapoznaj się z rozważanymi alternatywami i dlaczego wybrano je nad innymi.

W przypadku magazynu plików można rozważyć trzy podejścia:

  • Azure Blob Storage: wybrano opcję opłacalności, skalowalności i integracji z istniejącym środowiskiem platformy Azure.
  • Azure Files: Odrzucono z powodu wyższych kosztów dużego magazynu plików i niepotrzebnych obciążeń związanych z protokołem Bloku komunikatów serwera (SMB).
  • SQL Database FILESTREAM: odrzucono, aby uniknąć zwiększenia rozmiaru i złożoności bazy danych.

Ta dokumentacja uniemożliwia przyszłym deweloperom kwestionowanie, dlaczego nie były używane prostsze podejścia. Uzasadnienie decyzji jest zachowywane, a nie zostaje zapomniane z czasem.

Przechwytywanie założeń

Plany zakładają istniejące systemy, infrastrukturę i ograniczenia organizacyjne. Ustaw te założenia jako jawne.

Przykładowe założenia dotyczące przekazywania dokumentów:

  • Kontener employee-documents usługi Azure Blob Storage jest aprowizowany przez zespół infrastruktury przed rozpoczęciem programowania.
  • Istniejące uwierzytelnianie portalu zapewnia zweryfikowane tokeny identyfikatorów Entra firmy Microsoft, które mogą być zaufane do identyfikacji użytkowników.
  • Baza danych SQL ma wystarczającą pojemność dla innej tabeli metadanych bez konieczności rozszerzania magazynu.
  • Infrastruktura sieciowa obsługuje przesyłanie HTTP 50 MB bez ograniczeń serwera proxy lub zapory.

Jeśli jakiekolwiek założenie okaże się nieprawidłowe podczas implementacji, możesz ponownie przejrzeć plan i odpowiednio dostosować. Udokumentowane założenia sprawiają, że analiza wpływu jest prosta, gdy zmieniają się okoliczności.

Planowanie przyszłej ewolucji

Zastanów się, jak funkcja może ewoluować, i upewnij się, że architektura będzie obsługiwać prawdopodobne rozszerzenia.

W przypadku przekazywania dokumentów potencjalne przyszłe wymagania mogą obejmować:

  • Obsługa innych typów plików poza formatami PDF i DOCX.
  • Implementowanie udostępniania plików między pracownikami.
  • Dodawanie wersjonowania dokumentów.
  • Włączanie zbiorczego przesyłania wielu plików.
  • Integrowanie skanowania antywirusowego

Jeśli twoja architektura sprawia, że te rozszerzenia są trudne, rozważ, czy dostosowanie projektu początkowego jest uzasadnione. Nie implementujesz teraz przyszłych funkcji, ale unikasz zapuszczania się w ślepe zaułki, które sprawiają, że przyszłe zmiany są bolesne.

Udostępnianie i utrzymywanie planu podczas implementacji

Plan staje się twoim punktem odniesienia w tej implementacji. Deweloperzy powinni regularnie skonsultować się z planem, aby upewnić się, że ich kod jest zgodny z udokumentowaną architekturą.

Udostępnianie planu uczestnikom projektu

Po sfinalizowaniu planu udostępnij go odpowiednim uczestnikom projektu w celu weryfikacji:

  • Menedżerowie produktów: Sprawdź, czy plan spełnia wszystkie wymagania dotyczące specyfikacji.
  • Zespół ds. zabezpieczeń: Potwierdź, że mechanizmy kontroli zabezpieczeń spełniają standardy organizacyjne.
  • Zespół infrastruktury: Upewnij się, że proponowane zasoby platformy Azure można aprowizować i konfigurować.
  • Zespół architektury: Weryfikowanie zgodności z zasadami architektury organizacyjnej.

Przegląd interesariuszy wychwytuje problemy przed rozpoczęciem wdrażania. Jeśli opinia zespołu ds. zabezpieczeń ujawnia, że proponowane uwierzytelnianie jest niewystarczające, zaktualizuj plan przed napisaniem kodu.

Zaktualizuj plan zgodnie z potrzebami

Plany są dokumentami życia. W przypadku wykrycia podczas implementacji, że podejście nie działa zgodnie z oczekiwaniami, zaktualizuj plan, aby odzwierciedlał nowe podejście.

Jeśli zaplanowano przechowywanie postępu przesyłania w localStorage przeglądarki, ale to powoduje problemy w trybie przeglądania prywatnego, zaktualizuj plan, aby użyć stanu w pamięci. Udokumentuj, dlaczego zmiana była konieczna, aby zachować uzasadnienie.

Zachowaj synchronizację plan.md z rzeczywistą implementacją. W przypadku różnic w planie i kodzie plan traci wartość jako dokumentację referencyjną.

  • Czy podejścia do zabezpieczeń spełniają wymagania organizacji?
  • Czy schemat bazy danych jest projektowy zgodnie z konwencjami nazewnictwa?

Jeśli plan sugeruje użycie bazy danych, ale istniejący portal ma już jedną, prawdopodobnie jest to nadmierne użycie. Jeśli plan zaproponuje technologię, jakiej zespół unika, należy udokumentować przyczynę lub dostosować plan.

Typowe pułapki planowania, których należy unikać

Unikaj tych typowych błędów podczas tworzenia i przeglądania planów:

  • Pomijanie fazy planowania: przechodzenie bezpośrednio ze specyfikacji do kodu bez planu zwiększa ryzyko błędów architektury. Czas zainwestowany w planowanie płaci dywidendy, uniemożliwiając przeróbki.

  • Akceptowanie planów bez przeglądu: plany generowane przez sztuczną inteligencję są punktami wyjścia, a nie ostatecznymi projektami. Zawsze sprawdzaj krytycznie i sprawdzaj pod kątem określonego kontekstu.

  • Zbyt restrykcyjne wdrożenie: plany powinny kierować, a nie dyktować wszystkie szczegóły. Pozostaw deweloperom miejsce na podejmowanie odpowiednich decyzji taktycznych podczas wdrażania.

  • Ignorowanie konfliktów konstytucji: Jeśli plan narusza zasady konstytucji, natychmiast rozwiąż konflikt. Albo dostosować plan, aby spełnić lub zaktualizować konstytucję, jeśli zasada wymaga zmiany.

  • Zapominanie o aktualizowaniu planów: gdy implementacja ujawnia nowe informacje, zaktualizuj plan.md. Przestarzałe plany wprowadzają w błąd przyszłych programistów i zmniejszają wartość dokumentacji.

Podsumowanie

Plan techniczny przekształca specyfikację w architekturę umożliwiającą podejmowanie działań. Generowanie planów przy użyciu /speckit.plan z odpowiednim kontekstem dotyczącym stosu technologii i infrastruktury. Przejrzyj plany krytyczne, aby upewnić się, że obejmują wszystkie wymagania dotyczące specyfikacji, są zgodne z konstytucją i zapewniają wystarczające wskazówki dotyczące implementacji. Użyj zweryfikowanych planów, aby pokierować generowaniem i implementacją zadań. Traktuj plan.md jako żywy dokument, który rozwija się wraz ze zrozumieniem i zapewnia cenny kontekst dla całego cyklu projektowania.