tdd-spec（时分驱动规范）

TDD Spec — Test-Driven Specification Writer

[MANDATORY] You MUST ATTENTION use TaskCreate to break ALL work into small tasks BEFORE starting. NEVER skip task creation.

External Memory: For complex or lengthy work (research, analysis, scan, review), write intermediate findings and final results to a report file in plans/reports/ — prevents context loss and serves as deliverable.

Evidence Gate: MANDATORY IMPORTANT MUST ATTENTION — every claim, finding, and recommendation requires file:line proof or traced evidence with confidence percentage (>80% to act, <80% must verify first).

Rationalization Prevention — AI skips steps via these evasions. Recognize and reject: | Evasion | Rebuttal | | --- | --- | | "Too simple for a plan" | Simple + wrong assumptions = wasted time. Plan anyway. | | "I'll test after" | RED before GREEN. Write/verify test first. | | "Already searched" | Show grep evidence with file:line. No proof = no search. | | "Just do it" | Still need TaskCreate. Skip depth, never skip tracking. | | "Just a small fix" | Small fix in wrong location cascades. Verify file:line first. | | "Code is self-explanatory" | Future readers need evidence trail. Document anyway. | | "Combine steps to save time" | Combined steps dilute focus. Each step has distinct purpose. |

Graph Context (MANDATORY when graph.db exists): Before generating test specs, run graph impact analysis. This reveals cross-service consumers, event handlers, and implicit connections (MESSAGE_BUS, API_ENDPOINT, TRIGGERS_EVENT) that tests must cover.

Quick Summary

Goal: Generate or update test specifications in feature docs Section 15 (canonical TC registry) using the unified TC-{FEATURE}-{NNN} format. Supports 5 modes: TDD-first, implement-first, update (post-change/PR), sync, and from-integration-tests.

Be skeptical. Apply critical thinking, sequential thinking. Every claim needs traced proof, confidence percentages (Idea should be more than 80%).

MANDATORY IMPORTANT MUST ATTENTION Plan ToDo Task to READ the following project-specific reference doc: > Evidence-Based Reasoning — Speculation is FORBIDDEN. Every claim needs proof. > > 1. Cite file:line, grep results, or framework docs for EVERY claim > 2. Declare confidence: >80% act freely, 60-80% verify first, <60% DO NOT recommend > 3. Cross-service validation required for architectural changes > 4. "I don't have enough evidence" is valid and expected output > > BLOCKED until: - [] Evidence file path (file:line) - [] Grep search performed - [] 3+ similar patterns found - [] Confidence level stated > > Forbidden without proof: "obviously", "I think", "should be", "probably", "this is because" If incomplete → output: "Insufficient evidence. Verified: [...]. Not verified: [...]." > Cross-Cutting Quality — Check across all changed files: > > 1. Error handling consistency — same error patterns across related files > 2. Logging — structured logging with correlation IDs for traceability > 3. Security — no hardcoded secrets, input validation at boundaries, auth checks present > 4. Performance — no N+1 queries, unnecessary allocations, or blocking calls in async paths > 5. Observability — health checks, metrics, tracing spans for new endpoints - .claude/skills/tdd-spec/references/tdd-spec-template.md — TC template format - docs/project-reference/domain-entities-reference.md — Domain entity catalog, relationships, cross-service sync (read when task involves business entities/models) (content auto-injected by hook — check for [Injected:...] header before reading) - docs/test-specs/ — Test specifications by module (read existing TCs before generating new to avoid duplicates and maintain TC ID continuity)

Workflow:

1. Mode Detection — Determine mode: TDD-first, implement-first, update, sync, or from-integration-tests
2. Investigation — Analyze PBI/codebase/existing TCs/git changes based on mode
3. TC Generation — Generate TC outlines, review interactively with user
4. Write to Feature Doc — Upsert TCs into target feature doc Section 15
5. Dashboard Sync — Optionally update docs/test-specs/ cross-module dashboard
6. Next Steps — Suggest follow-on actions based on mode

Key Rules:

• Unified format: TC-{FEATURE}-{NNN} — feature codes in docs/project-reference/feature-docs-reference.md
• Source of truth: Feature docs Section 15 is the canonical TC registry
• Evidence required: Every TC MUST ATTENTION have Evidence: {FilePath}:{LineRange} or TBD (pre-implementation) for TDD-first mode
• Minimum 4 categories: Positive (happy path), negative (error handling), authorization (role-based access), edge cases
• Cross-cutting TC categories:

- Authorization TCs (mandatory): Authorized access succeeds, unauthorized access rejected, role-based visibility verified - Seed Data TCs (if applicable): Reference data exists, seeder runs correctly - Performance TCs (if applicable): Feature performs within SLA under production-like data volume - Data Migration TCs (if applicable): Data transforms correctly, rollback works, no data loss

• Interactive review: ALWAYS use AskUserQuestion to review TC list with user before writing

Quick Reference

Related Skills

Output Locations

Phase-Mapped Coverage: When a plan exists with multiple phases, generate test cases PER PHASE — not just per feature. Each phase's success criteria MUST ATTENTION have ≥1 test case.

Frontend/UI Context (if applicable)

When this task involves frontend or UI changes,

UI System Context — For ANY task touching .ts, .html, .scss, or .css files: MUST ATTENTION READ before implementing: 1. docs/project-reference/frontend-patterns-reference.md — component base classes, stores, forms 2. docs/project-reference/scss-styling-guide.md — BEM methodology, SCSS variables, mixins, responsive 3. docs/project-reference/design-system/README.md — design tokens, component inventory, icons Reference docs/project-config.json for project-specific paths.

• Component patterns: docs/project-reference/frontend-patterns-reference.md
• Styling/BEM guide: docs/project-reference/scss-styling-guide.md
• Design system tokens: docs/project-reference/design-system/README.md

Detailed Workflow

Phase 1: Mode Detection & Context

Detect mode from user prompt and context:

Must read FIRST:

1. docs/project-reference/feature-docs-reference.md — identify the correct {FEATURE} code for TC IDs
2. Target feature doc — check if Section 15 exists, read existing TCs to avoid ID collisions

If target feature doc doesn't exist:

• Suggest running /feature-docs first, OR
• Create a minimal Section 15 stub in the appropriate feature doc

Phase 2: Investigation

TDD-first mode:

1. Read the PBI/story document (from team-artifacts/pbis/ or user-provided)
2. Extract acceptance criteria
3. Identify test categories: CRUD operations, validation rules, authorization (mandatory), workflows, edge cases, seed data, performance data, data migration
4. Cross-reference with existing feature doc requirements (Sections 1-14)
5. Cross-reference PBI Authorization section → generate authorization TCs (unauthorized access rejection per role)
6. Cross-reference PBI Seed Data section → generate seed data TCs if reference/config data needed
7. Cross-reference PBI Data Migration section → generate migration TCs if schema changes exist

Implement-first mode:

1. Grep for commands/queries in the target service: grep -r "class.*Command.*:" src/Services/{service}/
2. Grep for entities and domain events
3. Trace code paths: Controller → Command → Handler → Entity → Event Handler
4. Identify testable behaviors from actual implementation

Update mode (post-change / post-bugfix / post-PR):

1. Read existing Section 15 TCs
2. git diff or git diff main...HEAD (for PRs) to find code changes since TCs were last updated
3. Identify: new commands/queries not covered, changed behaviors, removed features
4. For bugfixes: add a regression TC for the bug that was fixed (e.g., TC-GM-040: Regression — goal title validation bypass)
5. Generate gap analysis
6. Update both feature docs Section 15 AND docs/test-specs/ dashboard

Sync mode (bidirectional reconciliation):

1. Read feature docs Section 15 TCs for target module
2. Read docs/test-specs/{Module}/README.md TCs
3. Read test files: grep for test spec annotations in src/Services/{service}*.IntegrationTests/
4. Build 3-way comparison table:

| TC ID | In Feature Doc? | In test-specs/? | In Test Code? | Action Needed |
|-------|----------------|-----------------|---------------|---------------|
| TC-OM-001 | ✅ | ✅ | ✅ | None |
| TC-OM-025 | ✅ | ❌ | ✅ | Add to test-specs/ |
| TC-OM-030 | ❌ | ✅ | ❌ | Add to feature doc |

1. Reconcile: write missing TCs to whichever system lacks them
2. Feature docs remain source of truth — any conflict uses feature doc version

From-integration-tests mode (reverse-engineer specs from existing tests):

1. Grep for [Trait("TestSpec", "TC-...")] in target test project
2. For each test method: extract TC ID, method name, test description from comments
3. Read the test method body to generate GWT steps and evidence
4. Write extracted TCs to feature doc Section 15 (if not already there)
5. Useful when: tests were written before the spec system existed, or imported from another project

Phase 3: TC Generation with Interactive Review

1. Generate TC outlines as a summary table:

| TC ID | Name | Priority | Category | Status |
|-------|------|----------|----------|--------|
| TC-GM-037 | Create goal with cascading key results | P0 | CRUD | New |
| TC-GM-038 | Reject goal without required title | P1 | Validation | New |
| TC-GM-039 | External user cannot access goals | P0 | Permission | New |

1. Use AskUserQuestion to review with user:

Question: "These {N} test cases cover {feature}. Review the list:"
Options:
- "Approve as-is (Recommended)" — Proceed to writing
- "Add missing scenario" — Describe what's missing
- "Adjust priorities" — Change P0/P1/P2 assignments
- "Regenerate" — Re-analyze and try again

1. Iterate until user approves.

Phase 4: Write to Feature Doc Section 15

This is the canonical write — feature docs own the TCs.

1. Locate Section 15 in target feature doc
2. If Section 15 exists: append new TCs after existing ones, preserving existing TC IDs
3. If Section 15 doesn't exist: create it from template
4. Use Edit tool to upsert — never overwrite existing TCs

TC format (from tdd-spec-template.md):

#### TC-{FEATURE}-{NNN}: {Descriptive Test Name} [{Priority}]

**Objective:** {What this test verifies}

**Preconditions:**

- {Setup requirement}

**Test Steps:**
\`\`\`gherkin
Given {initial state}
And {additional context}
When {action}
Then {expected outcome}
And {additional verification}
\`\`\`

**Acceptance Criteria:**

- ✅ {Success behavior}
- ❌ {Failure behavior}

**Test Data:**
\`\`\`json
{ "field": "value" }
\`\`\`

**Edge Cases:**

- {Boundary condition}

**Evidence:** `{FilePath}:{LineRange}` or `TBD (pre-implementation)`

Evidence rules by mode:

• TDD-first: Evidence: TBD (pre-implementation) — will be updated after implementation
• Implement-first: Evidence: {actual file}:{actual lines} — trace to real code
• Update: Update existing evidence references if code moved

Phase 5: Update docs/test-specs/ Dashboard (Optional)

If docs/test-specs/{Module}/README.md exists:

1. Update the Implementation Index section with new TC→test method mappings
2. For TDD-first: map to expected test method names (will be created by /integration-test)
3. Update PRIORITY-INDEX.md with new TC entries in correct priority tier

Skip this phase if user says "skip dashboard" or if no docs/test-specs/ file exists for the module.

Phase 6: Next Step Suggestion

Based on mode, suggest via AskUserQuestion:

TDD-first:

1. "/integration-test — Generate test stubs from these TCs (Recommended)"
2. "/plan — Plan the feature implementation"
3. "Done for now — I'll implement later"

Implement-first:

1. "/integration-test — Generate integration tests (Recommended)"
2. "/workflow-review-changes — Review all changes"
3. "Done for now"

Update (post-change/PR):

1. "/integration-test — Generate/update tests for changed TCs (Recommended)"
2. "/test — Run existing tests to verify coverage"
3. "/test-specs-docs — Sync dashboard with updated TCs"
4. "Done for now"

Sync:

1. "/test-specs-docs — Sync dashboard after reconciliation (Recommended)"
2. "/integration-test — Generate tests for any TCs missing test coverage"
3. "Done for now"

From-integration-tests:

1. "/test-specs-docs — Sync dashboard with newly documented TCs (Recommended)"
2. "/test — Run tests to verify all documented TCs pass"
3. "Done for now"

Anti-Patterns

• ❌ Writing TCs to docs/test-specs/ as the primary destination (use feature docs Section 15)
• ❌ Using TC-{SVC}-{NNN} or TC-{SVC}-{FEATURE}-{NNN} format (use unified TC-{FEATURE}-{NNN})
• ❌ Generating TCs without reading existing Section 15 (causes ID collisions)
• ❌ Skipping the interactive review step (user must approve TC list)
• ❌ Writing TCs without Evidence field (every TC needs it, even if TBD)

See Also

• test-spec — Heavyweight test planning and investigation (use BEFORE this skill for complex features)
• test-specs-docs — Dashboard sync skill (aggregates TCs from feature docs to docs/test-specs/)
• integration-test — Integration test code generator (use AFTER this skill to generate test stubs)
• feature-docs — Feature doc creator (creates the Section 15 that this skill populates)
• refine — PBI refinement (feeds acceptance criteria into this skill's TDD-first mode)

Workflow Recommendation

MANDATORY IMPORTANT MUST ATTENTION — NO EXCEPTIONS: If you are NOT already in a workflow, you MUST ATTENTION use AskUserQuestion to ask the user. Do NOT judge task complexity or decide this is "simple enough to skip" — the user decides whether to use a workflow, not you: 1. Activate pbi-to-tests workflow (Recommended) — tdd-spec → tdd-spec-review → quality-gate 2. Execute /tdd-spec directly — run this skill standalone

Next Steps

MANDATORY IMPORTANT MUST ATTENTION — NO EXCEPTIONS after completing this skill, you MUST ATTENTION use AskUserQuestion to present these options. Do NOT skip because the task seems "simple" or "obvious" — the user decides:

• "/integration-test (Recommended)" — Generate integration test code from specs
• "/test" — Run tests to verify implementation
• "Skip, continue manually" — user decides

Closing Reminders

MANDATORY IMPORTANT MUST ATTENTION break work into small todo tasks using TaskCreate BEFORE starting. MANDATORY IMPORTANT MUST ATTENTION validate decisions with user via AskUserQuestion — never auto-decide. MANDATORY IMPORTANT MUST ATTENTION add a final review todo task to verify work quality. MANDATORY IMPORTANT MUST ATTENTION READ the following files before starting:

• IMPORTANT MUST ATTENTION never skip steps via "too simple" or "already searched" evasions. Plan anyway, test first, show grep evidence.
• IMPORTANT MUST ATTENTION cite file:line evidence for every claim. Confidence >80% to act, <60% do NOT recommend.
• IMPORTANT MUST ATTENTION check error handling, logging, security, performance, and observability across changed files.
• IMPORTANT MUST ATTENTION read frontend-patterns-reference, scss-styling-guide, design-system/README before any UI change.