Gardez les raisons derrière le code là où on peut les retrouver.
Pourquoi le système est ce qu'il est vit comme un savoir tribal, des fils de discussion perdus, des billets fermés, les descriptions ou commentaires d'une pull request que personne ne revisite, ou un document dans Confluence qui était déjà périmé au moment où il a été écrit. Une nouvelle personne dans l'équipe, ou un agent IA à qui l'on demande de changer le code, travaille à partir du code seul et prend des décisions à la volée sur ce qui était déjà décidé.
Le code porte la décision, mais perd le contexte et le raisonnement qui l'accompagnent.
Certaines approches du développement piloté par les spécifications traitent le plan comme toute l'histoire : détaillez assez la spécification avant de commencer, et le code en découlera. Quand ce n'est pas le cas, le verdict est habituellement que la spécification n'était pas assez bonne, comme si une meilleure spécification de départ avait produit le bon résultat. Ce serait rarement le cas. Un élément de travail rédigé avant que quiconque touche au code ne peut pas contenir la décision qu'un réviseur impose dans un fil de pull request, ni le cas particulier qui refaçonne l'approche à mi-chemin.
Une spécification de qualité reflète le travail terminé, pas l'idée à moitié aboutie dont elle est partie.
sdd travaille à l'intérieur du flux de travail que vous avez déjà, un système de suivi des éléments de travail, une pull request, des commentaires de revue, plutôt que d'exiger un rituel de rédaction de spécifications séparé à sa place. Ce qu'il conserve vit dans un dépôt qui lui est propre, séparé de la source : architecture, registres de décisions, conceptions de fonctionnalités et une fiche par élément de travail. Garder les spécifications à part signifie que vous pouvez les consulter et les gérer sans diluer votre fenêtre de contexte avec votre code source, et inversement.
Configurer le dépôt
Exécutez la commande d'initialisation dans un dépôt source, neuf ou vieux de plusieurs années. Elle écrit la configuration et génère les compétences d'agent, et une commande de diagnostic vérifie ensuite toute la chaîne, rapportant réussi, échoué ou sans signal plutôt que de présumer du succès à partir d'une sortie propre. Sur une base de code aux décisions non documentées depuis des années, une compétence de reconstruction rédige les spécifications à partir de l'historique des commits et des pull requests plutôt que de partir de rien.
sdd init · sdd doctorUne ébauche, pas la version finale
En théorie, un élément de travail comporte un user story, des exigences et des critères d'acceptation, mais ce n'est traditionnellement pas le cas. sdd vérifie que l'élément de travail les contient et, sinon, le renvoie avec un commentaire qui nomme chaque lacune. À partir d'un élément de travail conforme, sdd rédige une ébauche ancrée dans les décisions apparentées déjà enregistrées, un point de départ pour l'implémentation, pas un plan qu'elle doit suivre à la lettre.
sdd-spec-advisorImplémenter et itérer
L'ébauche devient la description de la pull request, et elle est réécrite à mesure que les réviseurs la remettent en question et que l'approche change. Ce qui atterrit dans le code n'est souvent pas ce que le billet disait au départ, et c'est attendu, pas un signe que la spécification a échoué.
sdd-implement · sdd-spec-reviewFinaliser selon ce qui s'est passé
Une fois la pull request approuvée, vous pouvez fusionner votre code. sdd rédige ensuite la spécification finale dans le dépôt séparé, à partir des changements fusionnés, de la description de la pull request et des commentaires de revue.
sdd-spec-advisorTout garder synchronisé
Une compétence planifiée, sdd-housekeeping, vérifie la dérive entre vos spécifications, le code, l'index RAG et le travail réellement livré. Elle signale une spécification périmée ou incohérente à corriger.
sdd-housekeepingVisualisez le dépôt de spécifications.
Chaque spécification est un fichier Markdown du dépôt de spécifications, et les relations entre spécifications se projettent dans un bloc de liens wiki que sdd garde synchronisé avec le frontmatter. Pointez un outil de graphe comme Obsidian vers le dossier, et vous regardez la même structure que sdd-housekeeping vérifie chaque jour.
- Le graphe est tracé à partir des mêmes liens que parcourt la consultation, de sorte que ce qui paraît relié dans Obsidian est ce qu'un agent atteint à un saut d'un résultat de recherche.
- Utiliser un outil comme Obsidian vous sort du code source et concentre votre attention de développement sur la structure et l'architecture.
Des décisions qui survivent au fil de discussion où elles ont été prises.
Chaque changement significatif a une spécification, ou en modifie une, qui dit à quoi il servait, ce qu'il doit satisfaire et à quoi il se rattache, et la spécification est consultable au moment où le changement suivant commence.
- Une spécification en vigueur qui régit un chemin modifié est mise à jour, ou le changement consigne pourquoi elle ne l'est pas; rien d'autre n'est obligatoire.
- La compétence d'entretien repère une référence brisée et une spécification devenue périmée par rapport à la base de code.
- Les spécifications portent des relations explicites entre elles, de sorte que la consultation ne met jamais en concurrence une décision avec celle qui l'a déjà remplacée.
- Le format n'a qu'une implémentation, dans la CLI, de sorte que les frontières de segments vues par l'auteur sont celles que l'index intègre.
- type work-item
- id SPEC-482
- refs src/billing/invoice.ts#refundOrder
- liens modifie ARCH-billing-invariants
Open source, auto-hébergé.
sdd est open source, publié sur npm sous @dependably/sdd, et s'installe dans un dépôt en une commande. Un développeur peut exécuter un miroir RAG personnel localement, là où la politique de l'entreprise sur l'IA locale le permet, ou un administrateur peut déployer une instance d'équipe sur une infrastructure partagée que l'agent de chaque développeur interroge par MCP à la place.