自定义配置

Rasen 提供三个层级的自定义：

项目配置

rasen/config.yaml 文件是为你的团队自定义 Rasen 的最简单方式。它让你可以：

• 设置默认模式 —— 跳过每条命令上的 --schema
• 注入项目上下文 —— AI 看到你的技术栈、约定等
• 添加逐产物规则 —— 特定产物的自定义规则

快速设置

rasen init

这会引导你交互式创建配置。或手动创建：

# rasen/config.yaml
schema: spec-driven

context: |
  Tech stack: TypeScript, React, Node.js, PostgreSQL
  API style: RESTful, documented in docs/api.md
  Testing: Jest + React Testing Library
  We value backwards compatibility for all public APIs

rules:
  proposal:
    - Include rollback plan
    - Identify affected teams
  specs:
    - Use Given/When/Then format
    - Reference existing patterns before inventing new ones

工作原理

默认模式：

# 不带配置
rasen new change my-feature --schema spec-driven

# 带配置 —— 模式自动
rasen new change my-feature

上下文和规则注入：

当生成任何产物时，你的上下文和规则被注入到 AI 提示中：

<context>
Tech stack: TypeScript, React, Node.js, PostgreSQL
...
</context>

<rules>
- Include rollback plan
- Identify affected teams
</rules>

<template>
[Schema's built-in template]
</template>

• 上下文出现在所有产物中
• 规则仅出现用于匹配的产物

模式解析顺序

当 Rasen 需要一个模式时，它按这个顺序检查：

1. CLI 标志：--schema <name>
2. 变更元数据（变更文件夹中的 .openspec.yaml）
3. 项目配置（rasen/config.yaml）
4. 默认（spec-driven）

自定义模式

当项目配置还不够时，创建你自己的模式，有一个完全自定义的工作流。自定义模式寄居在你的项目的 rasen/schemas/ 目录并与你的代码版本控制。

your-project/
├── rasen/
│   ├── config.yaml        # Project config
│   ├── schemas/           # Custom schemas live here
│   │   └── my-workflow/
│   │       ├── schema.yaml
│   │       └── templates/
│   └── changes/           # Your changes
└── src/

Fork 一个现有的模式

自定义最快的方式就是 fork 一个内建模式：

rasen schema fork spec-driven my-workflow

这会把整个 spec-driven 模式复制到 rasen/schemas/my-workflow/，你可以在那里自由编辑。

你得到什么：

rasen/schemas/my-workflow/
├── schema.yaml           # Workflow definition
└── templates/
    ├── proposal.md       # Template for proposal artifact
    ├── spec.md           # Template for specs
    ├── design.md         # Template for design
    └── tasks.md          # Template for tasks

现在编辑 schema.yaml 来改变工作流，或编辑模板来改变 AI 生成什么。

从头创建一个模式

对于一个完全全新的工作流：

# 交互式
rasen schema init research-first

# 非交互式
rasen schema init rapid \
  --description "Rapid iteration workflow" \
  --artifacts "proposal,tasks" \
  --default

模式结构

一个模式定义工作流中的产物和它们彼此如何依赖：

# rasen/schemas/my-workflow/schema.yaml
name: my-workflow
version: 1
description: My team's custom workflow

artifacts:
  - id: proposal
    generates: proposal.md
    description: Initial proposal document
    template: proposal.md
    instruction: |
      Create a proposal that explains WHY this change is needed.
      Focus on the problem, not the solution.
    requires: []

  - id: design
    generates: design.md
    description: Technical design
    template: design.md
    instruction: |
      Create a design document explaining HOW to implement.
    requires:
      - proposal    # Can't create design until proposal exists

  - id: tasks
    generates: tasks.md
    description: Implementation checklist
    template: tasks.md
    requires:
      - design

apply:
  requires: [tasks]
  tracks: tasks.md

关键字段：

模板

模板是指导 AI 的 markdown 文件。当创建该产物时它们被注入到提示中。

<!-- templates/proposal.md -->
## Why

<!-- Explain the motivation for this change. What problem does this solve? -->

## What Changes

<!-- Describe what will change. Be specific about new capabilities or modifications. -->

## Impact

<!-- Affected code, APIs, dependencies, systems -->

模板可以包含：

• AI 应该填写的小节标题
• 为 AI 提供指导的 HTML 注释
• 展示预期结构的示例格式

校验你的模式

在使用自定义模式之前，校验它：

rasen schema validate my-workflow

这会检查：

• schema.yaml 语法正确
• 所有引用的模板存在
• 无循环依赖
• 产物 ID 有效

使用你的自定义模式

一旦创建，使用你的模式：

# 在命令上指定
rasen new change feature --schema my-workflow

# 或在 config.yaml 中设置为默认
schema: my-workflow

调试模式解析

不确定使用哪个模式？检查：

# 看一个特定模式从哪里解析
rasen schema which my-workflow

# 列出所有可用模式
rasen schema which --all

输出展示它是来自你的项目、用户目录还是包：

Schema: my-workflow
Source: project
Path: /path/to/project/rasen/schemas/my-workflow

注： Rasen 也支持用户级模式在 ~/.rasen/schemas/（用 RASEN_HOME 覆盖位置）用于跨项目共享，但项目级模式在 rasen/schemas/ 被推荐，因为它们与你的代码版本控制。

示例

快速迭代工作流

最小开销快速迭代的最小工作流：

# rasen/schemas/rapid/schema.yaml
name: rapid
version: 1
description: Fast iteration with minimal overhead

artifacts:
  - id: proposal
    generates: proposal.md
    description: Quick proposal
    template: proposal.md
    instruction: |
      Create a brief proposal for this change.
      Focus on what and why, skip detailed specs.
    requires: []

  - id: tasks
    generates: tasks.md
    description: Implementation checklist
    template: tasks.md
    requires: [proposal]

apply:
  requires: [tasks]
  tracks: tasks.md

添加一个评审产物

Fork 默认并添加评审步骤：

rasen schema fork spec-driven with-review

然后编辑 schema.yaml 来添加：

  - id: review
    generates: review.md
    description: Pre-implementation review checklist
    template: review.md
    instruction: |
      Create a review checklist based on the design.
      Include security, performance, and testing considerations.
    requires:
      - design

  - id: tasks
    # ... existing tasks config ...
    requires:
      - specs
      - design
      - review    # Now tasks require review too

社区模式

Rasen 也支持通过独立仓库分布的社区维护模式。这些提供集成 Rasen 与其他工具或系统的固执己见的工作流，类似于 github/spec-kit 的社区扩展目录对 spec-kit 的做法。

社区模式不被库存进 Rasen 核心——它们住在自己的仓库中有自己的发布节奏。要使用一个，将模式包复制到你的项目的 rasen/schemas/<schema-name>/ 目录（每个仓库的 README 有安装指令）。

想贡献一个社区模式？用你仓库的链接开一个 issue，或提交 PR 为这个表添加一行。

另见

• CLI 参考：模式命令 —— 完整命令文档