ssd-dev

Synnovator (SSD) 项目开发指导。适用于以下场景：(1) 在本项目中启动任何开发任务；(2) 创建新功能或修复 bug；(3) 编写或审查代码；(4) 规划实施；(5) 更新文档。严格遵循“先规范、再开发”的原则，践行 TDD，杜绝反模式，并持续更新文档。

SKILL.md

--- frontmatter

name: ssd-dev
description: Synnovator (SSD) 项目开发指导。Use when (1) Starting any development task in this project, (2) Creating new features or fixing bugs, (3) Writing or reviewing code, (4) Planning implementation, (5) Updating documentation. Enforces spec-first development, TDD, anti-anti-patterns, and documentation updates.

SSD Development Guide

Synnovator (SSD) 项目的开发规范和最佳实践指南。

开发四原则

原则	规则文件	核心要求
Spec 先行	`rules/check-spec.md`	先确认需求，再写计划，最后实现
TDD 驱动	`rules/tdd.md`	Red → Green → Refactor
避免反模式	`rules/anti-anti-pattern.md`	Django Template, Admin 可配置, Wagtail 模式
文档更新	`rules/doc-updater.md`	代码变更 = 文档变更

开发流程总览

dot

digraph dev_flow {
    rankdir=TB;

    "1. 收到任务" [shape=doublecircle];
    "2. 检查 Spec" [shape=box];
    "3. 创建/更新 Plan" [shape=box];
    "4. 规划测试" [shape=box];
    "5. 编写测试 (Red)" [shape=box];
    "6. 编写代码 (Green)" [shape=box];
    "7. 重构 (Refactor)" [shape=box];
    "8. 更新文档" [shape=box];
    "9. 提交代码" [shape=doublecircle];

    "1. 收到任务" -> "2. 检查 Spec";
    "2. 检查 Spec" -> "3. 创建/更新 Plan";
    "3. 创建/更新 Plan" -> "4. 规划测试";
    "4. 规划测试" -> "5. 编写测试 (Red)";
    "5. 编写测试 (Red)" -> "6. 编写代码 (Green)";
    "6. 编写代码 (Green)" -> "7. 重构 (Refactor)";
    "7. 重构 (Refactor)" -> "8. 更新文档";
    "8. 更新文档" -> "9. 提交代码";
}

快速检查清单

开发前

• spec/ 中有对应功能文档？ → 没有则创建
• docs/plans/ 中有实施计划？ → 没有则创建
• 测试计划已确认？ → 写入 plan 文档

开发中

• 使用 Django Template (非 Jinja2)
• 内容在 Admin 可配置 (非硬编码)
• Page 用 add_child() 创建 (非 create())
• 列表页用 Index Page (非 Django View)
• msgid 用英文 (非中文)

开发后

• 所有测试通过 (uv run pytest)
• 更新 docs/plans/ 标记完成状态
• 更新 docs/architecture/ (如有模型变更)
• 更新 spec/ (如有需求变更)

常用命令

bash

# 开发服务器
make start

# 运行测试
uv run pytest

# 运行带覆盖率的测试
uv run pytest --cov=synnovator --cov-report=html

# 数据库迁移
uv run python manage.py makemigrations
uv run python manage.py migrate

# 翻译工作流
make translate-ui       # 提取字符串
make compile-translations  # 编译翻译

# 检查反模式
grep -r "{#" templates/ --include="*.html"  # Jinja2 注释
grep -rn "\.objects\.create" synnovator/ --include="*.py" | grep -i "page"  # 直接创建 Page

项目结构

code

ssd/
├── spec/                    # 功能规格 (业务目的)
│   ├── hackathon-prd.md    # 主 PRD
│   ├── behavior_requirements.csv
│   └── future/             # 未来功能
├── docs/
│   ├── plans/              # 实施计划 (技术方案)
│   ├── architecture/       # 架构文档
│   └── operational/        # 运营文档
├── synnovator/             # Django 应用
│   ├── hackathons/         # Hackathon 功能
│   ├── community/          # 社区功能
│   ├── users/              # 用户系统
│   └── ...
├── templates/              # Django 模板
└── .claude/skills/
    ├── ssd-dev/           # 本 skill
    └── wagtail-builder/   # Wagtail 最佳实践

规则详情

Rule 1: Spec 先行 (check-spec)

顺序: 目的 (Why) → 计划 (How) → 实现 (What)

bash

# 检查 spec 是否存在
ls spec/

# 检查 plan 是否存在
ls docs/plans/

See: rules/check-spec.md for templates and examples.

Rule 2: TDD 驱动 (tdd)

流程: 写测试 → 运行失败 → 写代码 → 运行通过 → 重构

bash

# 运行测试
uv run pytest synnovator/hackathons/tests/ -v

# 覆盖率检查
uv run pytest --cov=synnovator --cov-fail-under=80

See: rules/tdd.md for test templates and patterns.

Rule 3: 避免反模式 (anti-anti-pattern)

检查项	检测命令
Jinja2 语法	`grep -r "{#" templates/`
硬编码 URL	`grep -r "http" templates/`
直接创建 Page	`grep -rn "\.objects\.create" synnovator/`
中文 msgid	`grep -rn "_(" synnovator/ \| grep "[\u4e00-\u9fff]"`

See: rules/anti-anti-pattern.md for complete list.

Rule 4: 文档更新 (doc-updater)

变更类型	更新文档
需求变化	`spec/`
实施完成	`docs/plans/`
模型变更	`docs/architecture/`
新模式/反模式	`.claude/skills/`

See: rules/doc-updater.md for update workflow.

与其他 Skill 的关系

Skill	用途	何时使用
`wagtail-builder`	Wagtail CMS 开发最佳实践	创建 Page/Snippet/API
`ssd-dev` (本 skill)	项目开发规范	所有开发任务

使用顺序:

•先用 ssd-dev 确认规格和计划
•实现时参考 wagtail-builder 的技术细节

红线警告

以下行为绝对禁止:

禁止行为	原因	替代方案
跳过 spec 直接编码	需求不明确导致返工	先写 spec
先写代码后补测试	测试覆盖不全	TDD
使用 `Page.objects.create()`	破坏 Wagtail 树结构	`parent.add_child()`
中文作为 msgid	翻译系统崩溃	英文 msgid
代码变更不更新文档	文档过时	同步更新

更新本 Skill

如果在开发中发现:

•新的最佳实践 → 更新对应 rule 文件
•新的反模式 → 添加到 rules/anti-anti-pattern.md
•流程改进 → 更新 SKILL.md

bash

# Skill 文件位置
ls .claude/skills/ssd-dev/
# SKILL.md
# rules/check-spec.md
# rules/tdd.md
# rules/anti-anti-pattern.md
# rules/doc-updater.md

记住: 遵循规范就是最快的开发方式。跳过步骤只会增加返工。