Skip to content

spec-driven-dev.md

Latest commit

 

History

History
155 lines (109 loc) · 7.04 KB

spec-driven-dev.md

File metadata and controls

155 lines (109 loc) · 7.04 KB

Specification-Driven Development for DeepChat

Core Philosophy

Specification-Driven Development (SDD) eliminates the gap between requirements and implementation by making specifications the primary artifact. Specifications don't serve code—code serves specifications. When implementing features in DeepChat, start with clear specifications that define WHAT users need and WHY, before deciding HOW to implement.

In practice, SDD works best when the spec is concrete enough to drive design decisions, tests, and PR review. Prefer small, reviewable increments that keep spec → plan → code traceability.

Required Artifacts

Keep every active change in a lightweight SDD folder so reviewers can find the intent without hunting through code. Use one kebab-case folder per goal:

  • docs/features/<goal>/ - new features, user-visible capabilities, integrations, and tools
  • docs/issues/<goal>/ - bug fixes, regressions, failing tests, CI failures, reliability issues, and prompt/runtime problems
  • docs/architecture/<goal>/ - refactors, migrations, dependency boundaries, shared contracts, runtime architecture, and cross-module design

Each active goal folder contains:

  • spec.md - user stories, acceptance criteria, non-goals, constraints, open questions
  • plan.md - architecture decisions, event flow, data model, compatibility, test strategy
  • tasks.md - small, ordered tasks that map to commits/PRs

If a change is tiny, keep all three files short.

Workflow

  1. Feature Specification - Define user stories, acceptance criteria, business value, non-goals
  2. Implementation Plan - Architecture decisions, event flow, IPC surface, test strategy
  3. Task Breakdown - Small tasks that can be reviewed independently
  4. Implementation & Validation - TDD (pragmatic), Presenter patterns, UI consistency, quality gates

Before implementation, inspect existing docs and code, choose the correct SDD folder, and resolve every [NEEDS CLARIFICATION] marker. Move completed or stale goal folders to docs/archives/<goal>/. Add an archive note when historical documents reference code paths that moved or were removed. Delete documents that only describe removed code and have no reusable decision record.

Six Core Principles

1. Specification-First Development

Write clear requirements with measurable acceptance criteria before writing code. Mark any ambiguities with [NEEDS CLARIFICATION] and resolve them before implementation. Focus on user needs and business value, avoiding premature technical decisions.

2. Architectural Consistency

Follow DeepChat's existing architectural patterns:

  • Presenter Pattern: Add behavior in the appropriate module under src/main/presenter/
  • Event-Driven Communication: Use EventBus + event constants for main ↔ renderer flows
  • Secure IPC: Prefer typed IPC via src/preload/ (contextIsolation on); avoid ad-hoc channels
  • Type Definitions: Shared types live in src/shared/

Every feature should integrate seamlessly with existing Presenters and use the established event flow patterns.

对于 renderer-main 新能力，当前默认路径已经从 useLegacyPresenter() 转向 typed route / typed event + renderer/api/*Client。useLegacyPresenter() 只保留给兼容路径，不应再作为新代码模式复制。

3. Minimal Complexity

Start simple. Add complexity only when proven necessary. Avoid:

  • Future-proofing (build for now, not hypothetical future needs)
  • Unnecessary abstraction layers
  • Over-generalization
  • Premature optimization

Use framework features directly. Prefer a small “first increment” (e.g. Presenter method + critical test + minimal UI); if a change touches many files, explain why in the plan.

4. Compatibility & Migration

Prefer forward-looking designs, but treat stored user data, config, and external APIs as contracts. If a breaking change is necessary:

  • Document the migration path in the spec/plan
  • Include upgrade/rollback considerations (data, settings, UI defaults)
  • Keep user impact explicit (what changes, what might break)

5. UI Consistency

Maintain consistency across the codebase:

  • Vue 3 Composition API for all components
  • i18n for all user-facing strings in src/renderer/src/i18n/
  • Tailwind CSS following existing utility patterns
  • Follow existing component conventions (props, emits, composition patterns)

6. Test-Driven Approach (Pragmatic)

Use Vitest + Vue Test Utils for testing. Test files mirror source structure under /test/main/ and /test/renderer/. Write tests for critical paths and high-impact code. Not exhaustive: focus on value, not coverage.

Development Checklist

Specification Phase

  • User stories clearly defined
  • Acceptance criteria testable and measurable
  • Non-goals and constraints stated
  • Key UX states covered (loading/empty/error)
  • No [NEEDS CLARIFICATION] markers remain
  • Business value articulated

Planning Phase

  • Identify all involved Presenters
  • Design event flow (if cross-process communication required)
  • Define/verify IPC surface (src/preload/) and types (src/shared/)
  • Define shared types in src/shared/
  • Plan test coverage for critical paths
  • Identify risks (security/privacy/perf) and mitigations

Implementation Phase

  • Create/update test file
  • Implement Presenter method(s)
  • Implement UI component (if needed)
  • Add i18n keys (if user-facing)
  • Run: pnpm run format && pnpm run lint && pnpm run typecheck

Common Patterns

// 1. Typed Route / Client Method Signature
async methodName(params: InputType): Promise<OutputType>

// 2. EventBus Communication (Main Process)
eventBus.sendToRenderer(CONFIG_EVENTS.SETTING_CHANGED, SendTarget.ALL_WINDOWS, payload)

// 3. Renderer-main Integration
const settingsClient = new SettingsClient()
await settingsClient.update([{ key: 'fontSizeLevel', value: 2 }])

// 4. Vue 3 Component Pattern
<script setup lang="ts">
import { SettingsClient } from '../../api/SettingsClient'

const settingsClient = new SettingsClient()
// Composition API logic
</script>

Compatibility note:

  • 新 renderer-main 能力优先定义 shared/contracts/* 和 renderer/api/*Client
  • useLegacyPresenter() 不再是推荐模式
  • 如果必须临时保留 legacy transport，应先收口到 src/renderer/api/legacy/**，而不是直接进入业务模块
  • 不允许再创建第二个 quarantine 目录来承接 renderer-main legacy transport

Quick Reference

  • Presenters: src/main/presenter/**
  • Renderer clients: src/renderer/api/**
  • Tests: test/main/**/*, test/renderer/**/*
  • EventBus: src/main/eventbus.ts
  • Events: src/main/events.ts (main) and src/renderer/src/events.ts (renderer)
  • IPC bridge: src/preload/
  • i18n: src/renderer/src/i18n/
  • Shared types: src/shared/presenter.d.ts

Definition of Done (DoD)

A feature is “done” when:

  • The acceptance criteria are met (and ideally covered by tests)
  • Lint/typecheck/tests pass locally
  • User-facing strings use i18n keys
  • Any migrations or breaking changes are documented