GitHub Spec Kit-werkstromen en optionele opdrachten onderzoeken

  • 8 minuten

GitHub Spec Kit is een opensource-toolkit waarmee specificatiegestuurde ontwikkeling (SDD) mogelijk is door specificaties te integreren met AI-coderingsassistenten. Voordat u geavanceerde functies gaat verkennen, gaan we de basisconcepten bekijken.

Basisbeginselen van GitHub Spec Kit bekijken

GitHub Spec Kit richt zich op een fundamentele uitdaging in ai-ondersteunde ontwikkeling: context en consistentie behouden voor meerdere interacties met coderingsassistenten. Het biedt drie essentiële mogelijkheden:

  • Permanente artefacten: Specificaties, plannen en taken worden opgeslagen als Markdown-bestanden in uw opslagplaats.
  • Gestandaardiseerde werkstroom: Een gedefinieerd proces begeleidt u door de vier SDD-fasen: specificatie, planning, taakverdeling en implementatie.
  • Herbruikbare opdrachten: ingebouwde slash-opdrachten bevatten best practice prompting-patronen.

Kernonderdelen

GitHub Spec Kit implementeert de volgende kernonderdelen:

Onderdeel Purpose
specify CLI Initialiseert en beheert specificatiegestuurde projecten.
Markdown-artefactbestanden constitution.md, spec.md, plan.md en tasks.md drijven de ontwikkeling aan.
Slash-opdrachten /speckit.specify, , /speckit.plan/speckit.tasks, /speckit.implement roept GitHub Spec Kit-werkstromen aan.

AI-agenten

GitHub Spec Kit ondersteunt de volgende AI-agents: GitHub Copilot, Claude Code, Cursor, Windsurf, Amazon Q Developer en andere. Elke agent ontvangt sjablonen die zijn opgemaakt voor het specifieke promptformaat, terwijl dezelfde onderliggende artefact bestanden worden gebruikt.

Omgevingsvariabelen voor functietracking

GitHub Spec Kit maakt gebruik van omgevingsvariabelen om bij te houden welke functie u momenteel ontwikkelt. De SPECIFY_FEATURE variabele geeft de active feature directory aan.

In Git-werkstromen leidt GitHub Spec Kit de feature af van de naam van uw vertakking. Als u zich in de vertakking feature/document-uploadbevindt, werkt GitHub Spec Kit automatisch met de features/document-upload/ map.

Voor niet-Git-werkstromen of handmatige functiespecificatie stelt u de omgevingsvariabele expliciet in:

$env:SPECIFY_FEATURE = "001-document-upload"

Deze instelling vertelt GitHub Spec Kit om artefacten in de features/001-document-upload/ directory te lezen en te schrijven, ongeacht de Git-vertakking.

Deze functietracering zorgt ervoor dat wanneer u aanroept /speckit.plan, de AI het juiste spec.md bestand leest voor uw huidige functie in plaats van specificaties van verschillende functies te combineren.

GitHub Spec Kit integreren met Git-werkstromen

GitHub Spec Kit kan worden geïntegreerd in uw bestaande ontwikkelprocedures via verschillende mechanismen.

Integratie van versiebeheer

Alle GitHub Spec Kit-artefacten zijn gewone Markdown-bestanden die zijn opgeslagen in uw Git-opslagplaats. Deze aanpak biedt verschillende voordelen:

  • Wijzigingen bijhouden: elke wijziging in specificaties, plannen of taken maakt een Git-doorvoer. U kunt de geschiedenis van vereistewijzigingen bekijken, begrijpen waarom beslissingen zijn genomen en problematische wijzigingen terugdraaien.

  • Ontwikkeling op basis van vertakkingen: Functievertakkingen maken die zowel specificatieartefacten als implementatiecode bevatten. Deze aanpak houdt vereisten en implementatie gesynchroniseerd en maakt codebeoordeling uitgebreid. Revisoren zien zowel wat u bouwt (spec) als hoe u deze hebt gebouwd (code).

  • Werkstromen voor pull-aanvragen: wanneer u een pull-aanvraag voor een functie indient, neemt u spec.md, plan.md en tasks.md naast codewijzigingen op. Revisoren controleren of de implementatie overeenkomt met specificaties en of deze specificaties overeenkomen met projectdoelen.

Als u bijvoorbeeld een nieuwe functie implementeert, bevat uw functievertakking:

  • spec.md uploadvereisten definiëren.
  • plan.md een beschrijving van de Azure Blob Storage-architectuur.
  • tasks.md met implementatiestappen.
  • Broncode voor het implementeren van de functie.
  • Tests die de naleving van specificaties verifiëren.

Deze volledige afbeelding maakt een grondige beoordeling mogelijk. Als een revisor vraagt waarom bestanden beperkt zijn tot 50 MB, kunnen ze verwijzen naar spec.md en zien dat deze vereiste afkomstig is van discussies met belanghebbenden.

Integratiescenario voor AI-assistent - GitHub Copilot

GitHub Spec Kit werkt met GitHub Copilot via de chatinterface van Visual Studio Code. Nadat u de opdracht hebt uitgevoerd specify init --ai copilot, configureert de toolkit uw werkruimte om opdrachten te herkennen /speckit.* .

Wanneer u GitHub Copilot Chat opent en typt /speckit.specify, opent GitHub Copilot vooraf gedefinieerde sjablonen uit de .github/prompts/ map. Deze sjablonen helpen bij het structuren van de uitvoer van AI om alle benodigde specificatiesecties op te nemen: gebruikersverhalen, acceptatiecriteria, functionele vereisten, niet-functionele vereisten en edge-cases.

De integratie is naadloos. U beheert sjablonen niet handmatig. GitHub Spec Kit verwerkt sjabloon laden en contextinjectie automatisch. Uw taak is om functiebeschrijvingen te bieden en vragen te verduidelijken. GitHub Copilot verwerkt specificatieopmaak en volledigheid.

Projectstructuurconventies

GitHub Spec Kit organiseert artefacten met behulp van consistente mapstructuur:

my-project/
├── .github/
│   ├── agents/
│   └── prompts/
├── .specify/
│   ├── memory/
│   │   └── constitution.md
│   ├── scripts/
│   └── templates/
├── SourceCode/ 
│   └── ...
├── specs/
│   └── 001-document-upload-feature/
│       ├── plan.md
│       ├── spec.md
│       └── tasks.md

Deze structuur scheidt specificatieartefacten van implementatiecode en houdt deze in dezelfde opslagplaats. Functies worden opeenvolgend genummerd (001, 002, 003) om de ontwikkelingsvolgorde bij te houden.

Voor teams die gelijktijdig aan meerdere functies werken, heeft elke functie een eigen map met de volledige specificatie, het plan en de taken. Deze isolatie voorkomt verwarring en maakt parallelle werkzaamheden mogelijk zonder conflicten.

Ondersteuning voor continue werkstromen

GitHub Spec Kit ondersteunt iteratieve ontwikkeling via opdrachtketens. Nadat u initiële specificaties hebt gegenereerd, kunt u deze geleidelijk verfijnen:

  1. Eerste specificatie genereren: /speckit.specify.
  2. Hiaten identificeren: /speckit.clarify.
  3. Specificatie bijwerken op basis van antwoorden.
  4. Implementatieplan maken: /speckit.plan.
  5. Consistentie controleren: /speckit.analyze.
  6. Taken genereren: /speckit.tasks.
  7. Incrementeel implementeren: /speckit.implement.

Als de vereisten veranderen, kunt u op elk moment terugkeren naar eerdere fasen, artefacten bijwerken en downstreamartefacten opnieuw genereren. Als een belanghebbende van gedachten verandert over de bestandsgroottelimieten nadat u taken hebt gegenereerd, werkt u spec.md bij, genereert u plan.md opnieuw om de gevolgen van de architectuur weer te geven, genereert u tasks.md opnieuw met bijgewerkte validatiestappen en werkt u vervolgens de implementatiecode bij.

Deze flexibiliteit biedt ondersteuning voor echte ontwikkeling waar de vereisten zich ontwikkelen. De specificatie-first aanpak zorgt ervoor dat wijzigingen systematisch worden doorgevoerd in plaats van in code te worden gepatcht zonder documentatie bij te werken.

Gebruik de optionele uitbreidingsopdrachten van GitHub Spec Kit

Naast de belangrijkste werkstroomopdrachten biedt GitHub Spec Kit optionele opdrachten die de kwaliteit en consistentie van de specificatie verbeteren.

Gebruik /speckit.clarify voor gap-analyse

Met de /speckit.clarify opdracht wordt uw specificatie geanalyseerd om dubbelzinnigheden, ontbrekende details en onderopgegeven edge-zaken te identificeren. Nadat u een eerste specificatie hebt gegenereerd, roept u deze opdracht aan om de AI vragen te laten verduidelijken.

De AI beoordeelt uw specificatie en genereert vragen zoals:

  • "De specificatie vermeldt het uploaden van bestanden, maar geeft geen maximum aantal gelijktijdige uploads op. Moet er een limiet zijn?"
  • 'Foutafhandeling voor netwerkfouten is niet opgegeven. Wat moet er gebeuren als de uploadverbinding is verbroken?
  • "De specificatie vereist bestandsvalidatie, maar geeft geen validatiefoutberichten op. Wat moeten gebruikers zien?

Voor elke vraag biedt de AI vaak opties voor meerdere keuzen voor het oplossen van de kloof. U selecteert een optie of geeft een aangepast antwoord op en de AI werkt de specificatie dienovereenkomstig bij.

Deze interactieve verfijning onderschept problemen voordat de implementatie begint. Het is alsof u een ervaren analist uw specificaties bekijkt en verwijst naar wat u hebt gemist.

/speckit.analyze gebruiken voor consistentieverificatie

De /speckit.analyze opdracht voert consistentiecontrole tussen artefacten uit. Het controleert of uw plan alle specificatievereisten implementeert, dat taken betrekking hebben op alle planelementen en dat alles overeenkomt met de grondwet.

Voer deze opdracht uit nadat u plan.md en tasks.md hebt gegenereerd, maar voordat u begint met de implementatie. De AI identificeert inconsistenties:

  • 'Plan stelt voor om PostgreSQL te gebruiken, maar voor de grondwet is Azure SQL Database vereist.'
  • 'Specificatie vereist auditlogboekregistratie, maar plan beschrijft implementatie van logboekregistratie niet'.
  • 'Takenlijst laat databasemigratiescripts weg die in het plan worden vermeld.'

Elke geïdentificeerde inconsistentie is een probleem dat optreedt tijdens de implementatie of codebeoordeling. Als u ze tijdens de analysefase ophaalt, voorkomt u dat er opnieuw wordt gewerkt.

/speckit.checklist gebruiken voor kwaliteitsvalidatie

Met de /speckit.checklist opdracht worden aangepaste controlelijsten voor kwaliteit gegenereerd op basis van uw specificatie. Deze controlelijsten helpen bij het controleren van de volledigheid, duidelijkheid en consistentie van vereisten, zoals 'eenheidstests voor Engelse proza'.

De AI analyseert uw specificaties en produceert een controlelijst met verificatievragen:

  • "Heeft elk gebruikersverhaal overeenkomende acceptatiecriteria?"
  • 'Worden alle foutscenario's gedocumenteerd met specifieke foutberichten?'
  • "Bevatten niet-functionele vereisten meetbare succescriteria?"
  • 'Worden alle externe afhankelijkheden expliciet vermeld?'

U doorloopt de controlelijst en beantwoordt elke vraag. Eventuele 'nee'-antwoorden geven specificatieproblemen aan die u moet aanpakken.

Dit zelfbeoordelingsproces verbetert de kwaliteit van de specificatie voordat u met belanghebbenden deelt of doorgaat met de implementatie.

GitHub Spec Kit toepassen op verschillende ontwikkelscenario's

GitHub Spec Kit ondersteunt verschillende ontwikkelscenario's, behalve het bouwen van nieuwe functies.

Greenfield-ontwikkeling

Voor nieuwe projecten die van niets beginnen, excelleert GitHub Spec Kit bij het transformeren van productvisie op hoog niveau in concrete implementatie. U begint met /speckit.constitution het opstellen van projectprincipes en gebruikt /speckit.specify vervolgens voor elke functie terwijl u de toepassing iteratief bouwt.

Dit scenario is de primaire use-case van GitHub Spec Kit. De werkstroom is ontworpen voor ontwikkeling van 0-op-1 waarbij u iets maakt dat nog niet bestaat.

Uitbreiding van Brownfield

Voor bestaande toepassingen kunt u GitHub Spec Kit gebruiken om nieuwe functies toe te voegen terwijl de consistentie met bestaande codebase behouden blijft. Uw grondwet documenteer bestaande architectuurpatronen en beperkingen. Nieuwe functiespecificaties verwijzen naar deze vastgestelde patronen.

Wanneer u de functie voor het uploaden van documenten toevoegt aan een bestaande werknemersportal, erkent uw specificatie de bestaande React-front-end, .NET-back-end en De Azure-infrastructuur. Het plan laat zien hoe de nieuwe functie wordt geïntegreerd met de huidige architectuur in plaats van een afzonderlijke implementatie voor te stellen.

Herstructureren en moderniseren

GitHub Spec Kit kan helpen bij het herstructureren van inspanningen door de gewenste eindstatus als specificatie te behandelen. U documenteert wat de geherstructureerde code moet bereiken (dezelfde functionaliteit met een verbeterde structuur), maakt een plan voor de herstructureringsbenadering en genereert taken voor incrementele wijzigingen.

Deze gestructureerde benadering voor refactoring voorkomt het veelvoorkomende probleem dat je begint met refactoring en halverwege, met gedeeltelijk werkende code, de weg kwijtraakt.

Verkennende ontwikkeling

Voor situaties waarin u meerdere mogelijke benaderingen verkent, gebruikt u GitHub Spec Kit om meerdere plannen te genereren op basis van dezelfde specificatie. De stabiele specificatie vertegenwoordigt wat u wilt bereiken, terwijl verschillende plannen verschillende technische benaderingen verkennen.

U kunt één plan genereren met Behulp van Azure Blob Storage en een ander met behulp van Azure Files, beide uit dezelfde uploadspecificatie. Implementeer beide, vergelijk resultaten en kies de betere benadering op basis van werkelijke ervaring in plaats van veronderstellingen.

Samenvatting

De GitHub Spec Kit is een krachtige toolkit waarmee specgestuurde ontwikkeling mogelijk is door gestructureerde werkstromen, permanente artefacten en herbruikbare AI-opdrachtpatronen te integreren. Het transformeert hoe u met AI-coderingsassistenten zoals GitHub Copilot werkt door een systematische benadering te bieden voor het omzetten van specificaties in werkende implementaties. Met behulp van GitHub Spec Kit kunt u de afstemming tussen vereisten en code garanderen, de traceerbaarheid van beslissingen behouden en de samenwerking tussen ontwikkelteams verbeteren.