Skip to content
roadmap-guide logo

Roadmap 编写指南

roadmap-guide

在编写、更新、维护 roadmap.md 的时候触发

SKILL.md

Full skill instructions

Roadmap 编写指南

核心原则:roadmap 是导航图,不是教科书。信息密度 > 详细程度。

When to use

必须应用此规范的场景:

  • 向 docs/​roadmap.md 添加新版本/功能
  • 更新已有版本的状态
  • 记录架构决策的理由
  • 标记禁止事项和数据源限制

1. 简洁性原则(CRITICAL)

❌ 禁止冗余

删除这些内容:

  1. 示例代码(除非必需理解问题)

    ❌ 错误:
    **实现方案:**
    ```python
    # 20 行完整代码示例
    async def chat_with_loop(self, query: str) -> str:
        for i in range(15):
            ...
    

    ✅ 正确: 实现方案: chat_with_loop() 方法,最多 15 轮 ReAct 循环

  2. 重复信息(已在其他文档详述)

    ❌ 错误:详细解释 T+1/​T+2 确认规则
    ✅ 正确:确认规则见 `docs/​settlement-rules.md`
    
  3. 过长段落

    ❌ 错误:超过 3 行的描述段落
    ✅ 正确:每段 ≤ 3 行,优先使用列表/表格
    

2. 版本条目结构

每个版本条目遵循固定结构:

## vX.Y.Z 版本标题(状态标记)

### 核心目标
一句话说明此版本解决什么问题。

### 实现范围
- [x] 已完成项
- [ ] 待完成项

### 不做
- ❌ 明确排除的功能(防止范围蔓延)

状态标记:

  • ✅ 已完成
  • 🚧 进行中
  • 🔮 规划中

3. 对比表格

版本间对比使用表格,清晰展示差异:

| 维度 | v0.5.0 | v0.5.1 |
|------|--------|--------|
| 调用轮数 | 固定 1-2 轮 | 动态 N 轮 |
| 决策模式 | 一次性决定 | 边做边决策 |

4. 禁止事项 & 限制

使用统一格式记录:

## 禁止事项
- ❌ AI 执行交易操作(只给建议)
- ❌ 修改数据库 Schema

## 已知限制
**限制名称**(记录日期):
- 问题描述(1-2 行)
- 未来方案(可选)

5. ASCII 图表

架构/数据流优先使用 ASCII 图:

导入阶段:
  CSV → 算法 → BillFacts → AI 判断 → 回填 ActionLog

分析阶段:
  用户提问 → AI → Tools → 分析 → 建议

6. 触发机制

自动触发: 当检测到以下操作时,自动应用此 skill

  • 文件路径包含 roadmap.md
  • 提交信息包含 "roadmap" / "版本" / "规划"
  • 用户明确要求更新 roadmap

提醒文案:

正在编辑 roadmap.md
请遵循简洁性原则:
- 每段 ≤ 3 行
- 代码示例 ≤ 5 行或删除
- 无重复信息
- 优先使用列表/表格

More Other skills

Delegate independent tasks to specialized agents working concurrently with isolated context.

295.4K 206.3K
View

Applies Anthropic's official brand colors and typography to any sort of artifact that may benefit from having Anthropic's look-and-feel. Use it when brand colors or style guidelines, visual formatting, or company design standards apply.

179.7K 100.1K
View

Toolkit for styling artifacts with a theme. These artifacts can be slides, docs, reportings, HTML landing pages, etc. There are 10 pre-set themes with colors/fonts that you can apply to any artifact that has been creating, or can generate a new theme on-the-fly.

179.7K 89.5K
View

A set of resources to help me write all kinds of internal communications, using the formats that my company likes to use. Claude should use this skill whenever asked to write some sort of internal communications (status reports, leadership updates, 3P updates, company newsletters, FAQs, incident reports, project updates, etc.).

179.7K 76.1K
View

Fundamental design principles for writing maintainable, testable Python code.

40.2K 21.9K
View

Modern responsive layouts using container queries, fluid typography, CSS Grid, and mobile-first strategies.

40.2K 20K
View

Generate Playwright tests from scenarios using interactive browser exploration and validation.

39.7K 18.2K
View

Modern React state management with Redux Toolkit, Zustand, Jotai, and React Query for every state category.

40.2K 14.7K
View

GDPR-compliant data handling with consent management, data subject rights, and privacy controls.

40.2K 14.3K
View

Python error handling patterns including input validation, exception hierarchies, and partial failure handling. Use when implementing validation logic, designing exception strategies, handling batch processing failures, or building robust APIs.

40.2K 13.5K
View

Detailed multi-file refactor planning with safety checks and rollback guidance.

39.7K 13K
View