Discussion - Topic: GitHub Spec Kit

This week's topic: GitHub Spec Kit

Discussion resources to help guide the conversation will be posted below a few days before the meetup.

Zoom link will be added about 5 min before the event starts.

As described in Thoughtworks Technology Radar Vol. #34.

Spec-driven development featured prominently in our discussion this cycle. Two broad camps are emerging: teams that rely on the continually improving capabilities of coding agents with minimal structure, and those that favor defined workflows and detailed specifications.

Several of our teams are experimenting with spec-driven practices using GitHub Spec Kit, mostly in brownfield environments. A key concept in Spec Kit is the constitution, a foundational rulebook that aligns the software development lifecycle. In practice, teams reported that a useful constitution typically captures project scope, domain context, technology versions, coding standards and repository structure (for example, hexagonal architecture or layered modules). This shared context
helps agents operate within the intended architectural boundaries.

Teams also encountered challenges such as instruction bloat, where continually adding project context led to a growing agent instruction set and eventually context rot. One team addressed this by extracting reusable guidance into skills, keeping agent instructions lean and loading detailed context
only when needed.

In brownfield systems, much rework stems from unclear intent, hidden assumptions and late discovery of constraints. One team adopted a lifecycle of spec → plan → tasks → coding → review, which helped surface issues earlier. Over time they also moved repeatable context into files such as .github/prompts/speckit..prompt.md, making prompts shorter and agent behavior more consistent. Teams did report rough edges, including unnecessary defensive checks and overly verbose markdown outputs that increased cognitive load. Customizing Spec Kit templates and instructions — for example limiting the number of generated markdown files and reducing console verbosity — helped address some of these issues. Ultimately, experienced engineers, particularly those with strong clean coding and architectural practices, tend to extract the most value from spec-
driven workflows.

Discussion Resources :

Will be added a few days before the event.