도움말

Rasen으로 마이그레이션

이 가이드는 레거시 워크플로우에서 Rasen으로의 전환을 도와줍니다. 마이그레이션은 부드럽게 설계되었습니다. 기존 작업은 보존되며 새 시스템은 더 많은 유연성을 제공합니다.

무엇이 변경되었습니까?

Rasen은 이전의 단계 잠금 워크플로우를 유동적이고 작업 기반의 접근 방식으로 대체합니다. 다음이 주요 변화입니다.

측면	레거시	Rasen
명령	`/openspec:proposal`, `/openspec:apply`, `/openspec:archive`	일상 핵심: `/rasen:propose`, `/rasen:apply`, `/rasen:sync`, `/rasen:archive`(기본적으로 전체 확장 집합과 함께 설치됨)
워크플로우	한 번에 모든 산출물 생성	점진적으로 또는 한 번에 생성 — 선택입니다
돌아가기	어색한 단계 게이트	자연스러움 — 언제든지 모든 산출물 업데이트
사용자 정의	고정 구조	스키마 주도, 완전히 해킹 가능
구성	마커가 있는 `CLAUDE.md` + `project.md`	`rasen/config.yaml`의 깔끔한 구성

철학적 변화: 작업은 선형이 아닙니다. Rasen은 그렇게 가장하지 않습니다.

시작하기 전에

기존 작업은 안전합니다

마이그레이션 프로세스는 보존을 염두에 두고 설계되었습니다.

rasen/changes/의 활성 변경 — 완전히 보존됩니다. Rasen 명령으로 계속할 수 있습니다.
보관된 변경 — 건드리지 않습니다. 기록은 그대로 유지됩니다.
rasen/specs/의 주요 스펙 — 건드리지 않습니다. 이는 신뢰할 수 있는 단일 소스입니다.
CLAUDE.md, AGENTS.md 등의 콘텐츠 — 보존됩니다. 오직 rasen 마커 블록만 제거되며, 작성한 모든 내용은 유지됩니다.

제거되는 항목

대체되는 rasen 관리 파일만 해당됩니다.

항목	이유
레거시 슬래시 명령 디렉토리/파일	새로운 스킬 시스템으로 대체됨
`rasen/AGENTS.md`	구식 워크플로우 트리거
`CLAUDE.md`, `AGENTS.md` 등의 Rasen 마커	더 이상 필요 없음

도구별 레거시 명령 위치(예시 — 도구가 다를 수 있음):

Claude Code: .claude/commands/openspec/
Cursor: .cursor/commands/openspec-*.md
Windsurf: .windsurf/workflows/openspec-*.md
Cline: .clinerules/workflows/openspec-*.md
Roo: .roo/commands/openspec-*.md
GitHub Copilot: .github/prompts/openspec-*.prompt.md(IDE 확장만; Copilot CLI에서는 지원되지 않음)
기타(Augment, Continue, Amazon Q 등)

마이그레이션은 구성된 도구를 감지하고 레거시 파일을 정리합니다.

제거 목록이 길어 보이지만, 이는 모두 rasen이 원래 생성한 파일입니다. 자신의 콘텐츠는 절대 삭제되지 않습니다.

주의가 필요한 항목

한 파일이 수동 마이그레이션이 필요합니다.

openspec/project.md — 이 파일은 작성한 프로젝트 컨텍스트를 포함할 수 있으므로 자동으로 삭제되지 않습니다. 다음을 수행해야 합니다.

콘텐츠 검토
유용한 컨텍스트를 rasen/config.yaml로 이동(아래 지침 참조)
준비가 되면 파일 삭제

이 변경을 한 이유:

이전의 project.md는 수동적이었습니다. 에이전트가 읽을 수도, 읽지 않을 수도, 읽은 내용을 잊을 수도 있습니다. 신뢰성이 불일치했습니다.

새로운 config.yaml 컨텍스트는 모든 rasen 계획 요청에 적극적으로 주입됩니다. 이는 프로젝트 규칙, 기술 스택 및 규칙이 AI가 산출물을 생성할 때 항상 존재함을 의미합니다. 더 높은 신뢰성.

절충:

컨텍스트가 모든 요청에 주입되므로 간결함을 유지하고 싶을 것입니다. 정말 중요한 사항에 집중합니다.

기술 스택 및 주요 규칙
AI가 알아야 하는 명백하지 않은 제약
이전에 자주 무시되었던 규칙

완벽하게 얻는 것에 대해 걱정하지 마세요. 우리는 여전히 컨텍스트 주입이 어떤 것이 가장 잘 작동하는지 배우고 있으며, 실험하면서 개선할 것입니다.

마이그레이션 실행

rasen init 및 rasen update 모두 레거시 파일을 감지하고 동일한 정리 프로세스를 안내합니다. 상황에 맞는 것을 사용하세요.

새로 설치하면 full 프로파일(모든 워크플로우)을 기본값으로 사용합니다. 축소된 집합을 원하면 core(propose, explore, apply, sync, archive)로 전환합니다.
마이그레이션된 설치는 필요할 때 custom 프로파일을 작성하여 이전에 설치된 워크플로우를 보존합니다.

`rasen init` 사용

새 도구를 추가하거나 설정할 도구를 재구성하려면 이를 실행합니다.

rasen init

init 명령은 레거시 파일을 감지하고 정리 과정을 안내합니다.

Upgrading to the new rasen

Rasen now uses agent skills, the emerging standard across coding
agents. This simplifies your setup while keeping everything working
as before.

Files to remove
No user content to preserve:
  • .claude/commands/openspec/
  • rasen/AGENTS.md

Files to update
Rasen markers will be removed, your content preserved:
  • CLAUDE.md
  • AGENTS.md

Needs your attention
  • openspec/project.md
    We won't delete this file. It may contain useful project context.

    The new rasen/config.yaml has a "context:" section for planning
    context. This is included in every rasen request and works more
    reliably than the old project.md approach.

    Review project.md, move any useful content to config.yaml's context
    section, then delete the file when ready.

? Upgrade and clean up legacy files? (Y/n)

yes라고 하면 어떻게 됩니까:

레거시 슬래시 명령 디렉토리 제거
CLAUDE.md, AGENTS.md 등에서 Rasen 마커 제거(콘텐츠는 유지)
rasen/AGENTS.md 삭제
.claude/skills/에 새로운 스킬 설치
기본 스키마를 사용하여 rasen/config.yaml 생성

`rasen update` 사용

마이그레이션하고 기존 도구를 최신 버전으로 새로 고치려면 이를 실행합니다.

rasen update

update 명령은 또한 레거시 산출물을 감지하고 정리한 후 생성된 스킬/명령을 현재 프로파일 및 전달 방식 설정과 일치하도록 새로 고칩니다.

비대화형 / CI 환경

스크립트된 마이그레이션의 경우:

rasen init --force --tools claude

--force 플래그는 프롬프트를 건너뛰고 정리를 자동으로 수락합니다.

project.md를 config.yaml로 마이그레이션

이전의 openspec/project.md는 프로젝트 컨텍스트를 위한 자유형 마크다운 파일이었습니다. 새로운 rasen/config.yaml은 구조화되어 있으며 — 중요하게도 — 모든 계획 요청에 주입되므로 규칙이 AI가 작업할 때 항상 존재합니다.

Before (project.md)

# Project Context

This is a TypeScript monorepo using React and Node.js.
We use Jest for testing and follow strict ESLint rules.
Our API is RESTful and documented in docs/api.md.

## Conventions

- All public APIs must maintain backwards compatibility
- New features should include tests
- Use Given/When/Then format for specifications

After (config.yaml)

schema: spec-driven

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

rules:
  proposal:
    - Include rollback plan for risky changes
  specs:
    - Use Given/When/Then format for scenarios
    - Reference existing patterns before inventing new ones
  design:
    - Include sequence diagrams for complex flows

주요 차이점

project.md	config.yaml
자유형 마크다운	구조화된 YAML
텍스트의 한 덩어리	분리된 컨텍스트 및 산출물별 규칙
사용 시점이 명확하지 않음	컨텍스트는 모든 산출물에 나타남. 규칙은 일치하는 산출물에만 나타남
스키마 선택 없음	명시적 `schema:` 필드로 기본 워크플로우 설정

유지할 항목, 제외할 항목

마이그레이션할 때 선택적으로 접근합니다. 다음을 자문합니다. "AI가 모든 계획 요청에 필요합니까?"

context:에 적합한 후보

기술 스택(언어, 프레임워크, 데이터베이스)
주요 아키텍처 패턴(모노레포, 마이크로서비스 등)
명백하지 않은 제약("라이브러리 X를 사용할 수 없는 이유는...")
자주 무시되는 중요한 규칙

대신 rules:로 이동

산출물 특정 포맷팅("스펙에서 Given/When/Then 사용")
검토 기준("제안은 롤백 계획을 포함해야 함")
이는 일치하는 산출물에만 나타나므로 다른 요청을 더 가볍게 유지

전체적으로 제외

AI가 이미 아는 일반적인 모범 사례
요약할 수 있는 자세한 설명
현재 작업에 영향을 주지 않는 과거 컨텍스트

마이그레이션 단계

config.yaml 생성(이미 init에서 생성되지 않은 경우):
```
schema: spec-driven
```

컨텍스트 추가(간결하게 — 모든 요청에 포함됨):

context: |
  Your project background goes here.
  Focus on what the AI genuinely needs to know.

산출물별 규칙 추가(선택사항):

rules:
  proposal:
    - Your proposal-specific guidance
  specs:
    - Your spec-writing rules

유용한 모든 것을 이동한 후 project.md 삭제.

과도하게 생각하지 마세요. 필수 항목으로 시작하여 반복합니다. AI가 중요한 것을 놓치고 있다고 느끼면 추가합니다. 컨텍스트가 부풀어지면 잘라냅니다. 이는 살아있는 문서입니다.

도움이 필요합니까? 이 프롬프트 사용

project.md를 어떻게 정제할지 확실하지 않으면 AI 어시스턴트에게 요청합니다.

I'm migrating from rasen's old project.md to the new config.yaml format.

Here's my current project.md:
[paste your project.md content]

Please help me create a config.yaml with:
1. A concise `context:` section (this gets injected into every planning request, so keep it tight—focus on tech stack, key constraints, and conventions that often get ignored)
2. `rules:` for specific artifacts if any content is artifact-specific (e.g., "use Given/When/Then" belongs in specs rules, not global context)

Leave out anything generic that AI models already know. Be ruthless about brevity.

AI가 필수 항목과 잘라낼 수 있는 항목을 식별하는 데 도움을 줄 것입니다.

새로운 명령

명령 가용성은 프로파일에 따라 결정됩니다.

일상 명령(core 프로파일 부분 집합):

명령	목적
`/rasen:propose`	변경을 생성하고 한 단계로 계획 산출물 생성
`/rasen:explore`	구조 없이 아이디어를 생각
`/rasen:apply`	tasks.md의 작업 구현
`/rasen:archive`	변경을 최종 처리하고 보관

확장된 워크플로우(커스텀 선택):

명령	목적
`/rasen:new`	새로운 변경 스캐폴드 시작
`/rasen:continue`	다음 산출물 생성(한 번에 하나씩)
`/rasen:ff`	빠른 전진 — 한 번에 계획 산출물 생성
`/rasen:verify`	구현이 스펙과 일치하는지 검증
`/rasen:sync`	델타 스펙을 주 스펙으로 병합
`/rasen:bulk-archive`	한 번에 여러 변경 보관
`/rasen:onboard`	안내 종합 온보딩 워크플로우

기본 full 프로파일이 이미 포함되어 있습니다. 일상 집합만 원하면 core로 전환하거나 rasen config profile로 조정한 후 rasen update를 실행합니다.

레거시에서의 명령 매핑

레거시	Rasen 동등물
`/openspec:proposal`	`/rasen:propose`(기본값) 또는 `/rasen:new` 다음 `/rasen:ff`(확장됨)
`/openspec:apply`	`/rasen:apply`
`/openspec:archive`	`/rasen:archive`

새로운 기능

이 기능은 확장된 워크플로우 명령 집합의 일부입니다.

세분화된 산출물 생성:

/rasen:continue

종속성을 기반으로 한 번에 하나의 산출물을 생성합니다. 각 단계를 검토하려는 경우 사용합니다.

탐색 모드:

/rasen:explore

변경을 커밋하기 전에 파트너와 함께 아이디어를 생각합니다.

새로운 아키텍처 이해

단계 잠금에서 유동적으로

레거시 워크플로우는 선형 진행을 강제했습니다.

┌──────────────┐      ┌──────────────┐      ┌──────────────┐
│   PLANNING   │ ───► │ IMPLEMENTING │ ───► │   ARCHIVING  │
│    PHASE     │      │    PHASE     │      │    PHASE     │
└──────────────┘      └──────────────┘      └──────────────┘

If you're in implementation and realize the design is wrong?
Too bad. Phase gates don't let you go back easily.

Rasen은 단계가 아닌 작업을 사용합니다.

         ┌───────────────────────────────────────────────┐
         │           ACTIONS (not phases)                │
         │                                               │
         │     new ◄──► continue ◄──► apply ◄──► archive │
         │      │          │           │             │   │
         │      └──────────┴───────────┴─────────────┘   │
         │                    any order                  │
         └───────────────────────────────────────────────┘

종속성 그래프

산출물은 방향 그래프를 형성합니다. 종속성은 게이트가 아닌 인에이블러입니다.

                        proposal
                       (root node)
                            │
              ┌─────────────┴─────────────┐
              │                           │
              ▼                           ▼
           specs                       design
        (requires:                  (requires:
         proposal)                   proposal)
              │                           │
              └─────────────┬─────────────┘
                            │
                            ▼
                         tasks
                     (requires:
                     specs, design)

/rasen:continue를 실행하면 준비된 항목을 확인하고 다음 산출물을 제시합니다. 또한 여러 준비된 산출물을 모든 순서로 생성할 수 있습니다.

스킬 vs 명령

레거시 시스템은 도구 특정 명령 파일을 사용했습니다.

.claude/commands/openspec/
├── proposal.md
├── apply.md
└── archive.md

Rasen은 신흥 스킬 표준을 사용합니다.

.claude/skills/
├── rasen-explore/SKILL.md
├── rasen-new-change/SKILL.md
├── rasen-continue-change/SKILL.md
├── rasen-apply-change/SKILL.md
└── ...

스킬은 여러 AI 코딩 도구에서 인식되며 더 풍부한 메타데이터를 제공합니다.

기존 변경 계속

기존의 진행 중인 변경은 Rasen 명령과 원활하게 작동합니다.

레거시 워크플로우의 활성 변경이 있습니까?

/rasen:apply add-my-feature

Rasen은 기존 산출물을 읽고 중단된 곳에서 계속합니다.

기존 변경에 더 많은 산출물을 추가하고 싶습니까?

/rasen:continue add-my-feature

이미 존재하는 항목을 기반으로 생성할 준비가 된 항목을 표시합니다.

상태를 확인해야 합니까?

rasen status --change add-my-feature

새로운 구성 시스템

config.yaml 구조

# 필수: 새로운 변경의 기본 스키마
schema: spec-driven

# 선택사항: 프로젝트 컨텍스트(최대 50KB)
# 모든 산출물 지침에 주입됨
context: |
  Your project background, tech stack,
  conventions, and constraints.

# 선택사항: 산출물별 규칙
# 일치하는 산출물에만 주입됨
rules:
  proposal:
    - Include rollback plan
  specs:
    - Use Given/When/Then format
  design:
    - Document fallback strategies
  tasks:
    - Break into 2-hour maximum chunks

스키마 해석

사용할 스키마를 결정할 때 rasen은 순서대로 확인합니다.

CLI 플래그: --schema <name>(가장 높은 우선순위)
변경 메타데이터: 변경 디렉토리의 .openspec.yaml
프로젝트 구성: rasen/config.yaml
기본값: spec-driven

사용 가능한 스키마

스키마	산출물	가장 적합
`spec-driven`	proposal → specs → design → tasks	대부분의 프로젝트

사용 가능한 모든 스키마 나열:

rasen schemas

커스텀 스키마

자신의 워크플로우를 생성합니다.

rasen schema init my-workflow

또는 기존 것을 포크합니다.

rasen schema fork spec-driven my-workflow

자세한 내용은 사용자 정의를 참조합니다.

문제 해결

"Legacy files detected in non-interactive mode"

CI 또는 비대화형 환경에서 실행 중입니다. 사용합니다.

rasen init --force

마이그레이션 후 명령이 나타나지 않음

IDE를 다시 시작합니다. 스킬은 시작 시 감지됩니다.

"Unknown artifact ID in rules"

rules: 키가 스키마의 산출물 ID와 일치하는지 확인합니다.

spec-driven: proposal, specs, design, tasks

유효한 산출물 ID를 보려면 이를 실행합니다.

rasen schemas --json

구성이 적용되지 않음

파일이 rasen/config.yaml에 있는지 확인합니다(.yml 아님)
YAML 구문 유효성 검사
구성 변경은 즉시 적용됩니다 — 다시 시작 필요 없음

project.md가 마이그레이션되지 않음

시스템은 의도적으로 project.md를 보존합니다. 사용자 정의 콘텐츠를 포함할 수 있기 때문입니다. 수동으로 검토하고, 유용한 부분을 config.yaml로 이동한 후 삭제합니다.

정리될 항목을 보고 싶습니까?

init을 실행하고 정리 프롬프트를 거부합니다. — 변경 없이 전체 감지 요약을 볼 수 있습니다.

빠른 참조

마이그레이션 후 파일

project/
├── rasen/
│   ├── specs/                    # 변경 없음
│   ├── changes/                  # 변경 없음
│   │   └── archive/              # 변경 없음
│   └── config.yaml               # NEW: 프로젝트 구성
├── .claude/
│   └── skills/                   # NEW: Rasen 스킬
│       ├── rasen-propose/        # full 프로파일(기본값); core 프로파일은 이 부분 집합 유지
│       ├── rasen-explore/
│       ├── rasen-apply-change/
│       ├── rasen-sync-specs/
│       └── ...                   # full 프로파일이 new/continue/ff/등도 추가
├── CLAUDE.md                     # rasen 마커 제거, 콘텐츠는 보존
└── AGENTS.md                     # rasen 마커 제거, 콘텐츠는 보존

사라진 항목

.claude/commands/openspec/ — .claude/skills/로 대체됨
rasen/AGENTS.md — 구식
openspec/project.md — config.yaml로 마이그레이션 후 삭제
CLAUDE.md, AGENTS.md 등의 Rasen 마커 블록

명령 치트시트

/rasen:propose      빠르게 시작(기본 core 프로파일)
/rasen:apply        작업 구현
/rasen:archive      완료 및 보관

# 확장된 워크플로우(활성화된 경우):
/rasen:new          변경 스캐폴드
/rasen:continue     다음 산출물 생성
/rasen:ff           계획 산출물 생성

도움 받기

Discord: discord.gg/YctCnvvshC
GitHub Issues: github.com/DumoeDss/rasen/issues
문서: docs/opsx.md 전체 Rasen 참조