mcpField
D
docs-to-types

docs-to-types

github.com/oscabriel开发6247 次安装4 周前更新
代码仓库

关于 docs-to-types

docs-to-types 是一项开发技能，将经过确认的文档事实转化为类型化架构，供需要在编码前明确领域模型和模块边界的团队使用。它先检查项目上下文并处理歧义，再规划类型、接口、适配器和依赖结构；不实现业务行为。

主要功能

  1. 01提取架构事实并关联来源
  2. 02歧义或冲突时暂停确认
  3. 03规划类型、接口与模块结构
  4. 04定义生产和测试调用链
  5. 05运行类型与架构检查

适用场景

  1. 01将已批准的设计文档转为类型结构
  2. 02在实现前明确模块边界与依赖方向
  3. 03为生产和测试定义适配器接口

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/oscabriel/skills --skill docs-to-types

安装后在 Claude Code 中输入/docs-to-types确认已加载。

附带文件REFERENCE.md

详细介绍

从文档到类型

用于将已澄清的文字转化为类型化架构的前置架构技能。如果团队掌握了持久的领域或架构事实，类型系统和模块图也应体现这些事实。

不适用于一般性盘问、重构审查或第一个 TDD 切片。CONTEXT.md、ADR 和盘问笔记是源材料，不是最终的架构框架。

首要原则

不要实现业务行为。将已批准的上下文压缩为完整的预期类型化架构：

  • 规范领域类型、架构、品牌类型和不变量
  • 可排除无效状态的判别联合／状态模型
  • 用于解析从系统边界进入的值的智能构造器／解析器
  • 遵循项目约定的服务／接口接缝
  • 类型化结果／错误族和错误转换边界
  • 生产／测试适配器插槽
  • 遵循项目约定的组合／层／模块拓扑
  • 生产和测试调用栈
  • 在可行时检查依赖方向

不要创建业务工作流、真实持久化／网络逻辑、产品行为、事后重构、通用变更／结果框架，或伪装成完整实现的虚假生产逻辑。

先阅读

  1. AGENTS.md 和项目编码规则
  2. CONTEXT-MAP.md（如果存在）
  3. 相关的 CONTEXT.md 文件
  4. 相关的 docs/adr/*
  5. 已批准的 grill-with-docs 笔记／规格
  6. 目标区域附近的现有源代码

如果没有上下文文档／ADR，也没有已批准的 grill-with-docs 输出，请停止并建议使用 grill-with-docs。

工作流

1. 提取架构事实

编辑前，先生成事实表：

| Fact                                        | Source     | Code artifact         | Confidence |
| ------------------------------------------- | ---------- | --------------------- | ---------- |
| Link Catalog is the application-facing seam | CONTEXT.md | `LinkCatalog` service | high       |

包括领域名称、所有权边界、依赖方向、调用栈、适配器选择、运行时约束、类型化错误，以及必须留在适配器之后的基础设施。

2. 歧义关卡

如果文档、代码或用户计划彼此冲突，提出一个具体问题并等待答复。

如果某个文字事实无法清晰地表示为类型、接缝、适配器、状态、错误或依赖规则，就将领域语言视为仍有歧义。

示例：CONTEXT.md 中写的是“Operator”，但代码中写的是“User”和“Actor”。哪个才是规范名称？

3. 提出类型化结构

编辑前，除非用户要求直接实现，否则列出：

  • 要创建／更新的文件
  • 领域类型／架构／品牌类型／不变量／智能构造器
  • 状态模型／判别联合
  • 服务／接口接缝
  • 类型化结果／错误族
  • 生产和测试调用栈
  • 适配器插槽／存根
  • 架构检查
  • 明确排除的业务逻辑

请求批准。

4. 仅编码类型化结构

获批后，编写可编译的代码，构建完整的预期类型化结构。

规则：

  • 完全使用项目中的领域名称。
  • 优先使用深层模块：接口精简，将复杂性隐藏在接缝之后。
  • 遵循项目关于服务、接口、DI、组合、分层、工厂、提供者或注册表的约定。
  • 使用项目原生的类型化模式建模缺失值、校验、变体、状态和预期失败。
  • 将 HTTP／UI／CLI 传输细节留在边界处。
  • 将存储、SQL、队列、RPC 客户端、SDK 和第三方 API 留在适配器之后。
  • 如果可以通过机械方式检查依赖方向，则添加架构测试／lint／导入规则。

允许的代码深度和示例请参见 REFERENCE.md。

5. 验证并汇报

运行范围明确的检查：类型检查、lint／静态检查，以及新增的架构测试。最终回复应说明：已编码的事实、变更的文件、生产／测试调用栈、适配器插槽、已运行的检查，以及尚未实现的业务逻辑。

评论

支持 Markdown