도움말

문제 해결

구체적인 문제에 대한 구체적인 수정사항. 각 항목이 증상을 명명하고, 한 문장으로 가능한 원인을 설명하고, 수정사항을 제공합니다. 여기서 문제가 보이지 않으면 FAQ가 도움이 될 수 있으며 Discord는 확실히 도움이 됩니다.

설치 및 설정

`rasen: command not found`

CLI가 설치되지 않았거나 쉘이 찾을 수 없습니다. 전역으로 설치하고 확인합니다.

npm install -g @atelierai/rasen@latest
rasen --version

설치되었지만 여전히 찾을 수 없으면 전역 npm bin 디렉토리가 아마도 PATH에 없을 것입니다. npm bin -g를 실행하여 전역 바이너리가 어디에 있는지 확인하고, 해당 경로가 셸 프로필에 있는지 확인합니다.

"Requires Node.js 20.19.0 or higher"

Rasen은 Node 20.19.0+에서 실행됩니다. 버전을 확인하고 필요하면 업그레이드합니다.

node --version

bun을 사용하여 rasen을 설치하면 rasen은 여전히 Node에서 실행되므로 PATH에서 사용 가능한 Node 20.19.0+이 필요합니다. 설치를 참조하세요.

`rasen init`이 AI 도구를 구성하지 않았습니다

Init은 설정할 도구를 묻습니다. 도구를 건너뛰거나 다른 도구를 추가하려면 다시 실행하거나 비대화형 양식을 사용합니다.

rasen init --tools claude,cursor

도구 ID의 전체 목록은 지원 도구에 있습니다. --tools all을 모든 항목에, --tools none을 도구 설정 건너뛰기에 사용합니다.

명령이 나타나지 않습니다

/rasen:propose(또는 도구의 동등물)가 나타나지 않거나 아무것도 수행하지 않으면 이 목록을 아래로 작업합니다. 확인하기 가장 빠른 순서로 정렬됩니다.

잘못된 위치에 있을 수 있습니다. 슬래시 명령은 터미널이 아니라 AI 보조자의 채팅에 있습니다. 쉘에 /rasen:propose를 입력하면 그것이 문제입니다. 명령이 작동하는 방법을 참조하세요.
파일을 다시 생성합니다. 프로젝트 루트에서:
```
rasen update
```
이렇게 하면 구성된 모든 도구에 대한 스킬 및 명령 파일이 다시 작성됩니다.
보조자를 다시 시작합니다. 대부분의 도구는 시작 시 스킬과 명령을 스캔합니다. 새로운 창이 보통 그렇게 합니다.
파일이 존재하는지 확인합니다. Claude Code의 경우 .claude/skills/가 rasen-* 폴더를 포함하는지 확인합니다. 다른 도구는 자신의 디렉토리를 사용하며, 모두 지원 도구에 나열됩니다.
이 프로젝트를 초기화했는지 확인합니다. 스킬은 프로젝트별로 작성됩니다. 리포지토리를 클론하거나 폴더를 전환한 경우 거기서 rasen init(또는 rasen update)를 실행합니다.
도구가 명령 파일을 지원하는지 확인합니다. 몇 가지 도구(Kimi CLI, Trae, ForgeCode, Mistral Vibe)는 생성된 rasen-* 명령 파일을 받지 않습니다. 대신 스킬 기반 호출을 사용합니다. 형식은 도구별로 다릅니다. 지원 도구 및 명령이 작동하는 방법을 참조하세요.

변경으로 작업하기

"Change not found"

명령이 의도한 변경을 알 수 없습니다. 명시적으로 이름을 지정하거나 존재하는 것을 확인합니다.

rasen list                    # see active changes
/rasen:apply add-dark-mode        # name the change in chat

또한 올바른 프로젝트 디렉토리에 있는지 확인합니다.

"No artifacts ready"

모든 산출물이 이미 생성되었거나 종속성을 기다리면서 차단됩니다. 차단되는 항목을 확인합니다.

rasen status --change <name>

그 다음 먼저 누락된 종속성을 생성합니다. 순서를 기억합니다. 제안이 스펙과 설계를 활성화합니다. 스펙과 설계가 함께 작업을 활성화합니다.

`rasen validate`이 경고 또는 오류를 보고합니다

검증은 구조 문제에 대한 스펙과 변경을 확인합니다. 메시지를 읽으세요. 파일과 문제를 명명합니다.

rasen validate <name>           # validate one item
rasen validate --all            # validate everything
rasen validate --all --strict   # stricter checks, good for CI

일반적인 원인은 누락된 필수 섹션(시나리오 없는 스펙 등) 또는 형식이 잘못된 델타 헤더입니다. 파일을 수정하고 다시 실행합니다. CLI 참조는 출력 형식을 문서화합니다.

AI가 불완전하거나 잘못된 산출물을 생성했습니다

AI에 충분한 컨텍스트가 없었습니다. 몇 가지 레버가 도움이 됩니다.

스택 및 규칙이 모든 요청에 주입되도록 rasen/config.yaml에 프로젝트 컨텍스트를 추가합니다. 사용자 정의를 참조하세요.
스펙에만 적용되는 지침을 위해 산출물별 rules:을 추가합니다.
제안할 때 더 자세한 설명을 제공합니다.
확장된 /rasen:continue를 사용하여 한 번에 하나의 산출물을 생성하고 각각을 검토합니다. /rasen:ff가 모두 한 번에 하지 않는 대신.

보관을 마칠 수 없습니다. 또는 불완전한 작업에 대해 경고합니다

보관은 불완전한 작업에서 차단하지 않지만 경고합니다. 보관은 보통 작업이 완료되었음을 의미하기 때문입니다. 작업이 의도적으로 남으면(부분 변경을 파일하는 경우) 진행합니다. 그렇지 않으면 먼저 작업을 완료합니다. 보관은 또한 아직 동기화하지 않은 경우 델타 스펙을 주 스펙으로 동기화하는 것을 제공할 것입니다. 그렇게 하지 않을 이유가 있으면 예를 말합니다.

구성

내 `config.yaml`이 적용되지 않습니다

일반적인 세 가지 용의자:

잘못된 파일 이름. .yml이 아니라 rasen/config.yaml이어야 합니다.
잘못된 YAML. YAML 유효성 검사기를 통해 실행합니다. CLI도 줄 번호와 함께 구문 오류를 보고합니다.
재시작을 예상했습니다. 필요하지 않습니다. 구성 변경은 즉시 적용됩니다.

"Unknown artifact ID in rules: X"

rules: 아래의 키가 스키마의 산출물과 일치하지 않습니다. 기본 spec-driven 스키마의 경우 유효한 ID는 proposal, specs, design, tasks입니다. 모든 스키마의 ID를 보려면:

rasen schemas --json

"Context too large"

context: 필드는 의도적으로 50KB로 제한되므로 모든 요청에 주입됩니다. 요약하거나, 긴 문서를 붙여넣는 대신 링크합니다. 린 컨텍스트는 또한 더 좋고 빠른 결과를 생성합니다.

"Schema not found"

참조한 스키마 이름이 존재하지 않습니다. 사용 가능한 항목을 나열하고 철자를 확인합니다.

rasen schemas                    # list available schemas
rasen schema which <name>        # see where a schema resolves from
rasen schema init <name>         # create a custom one

사용자 정의를 참조하세요.

레거시 워크플로우에서 마이그레이션

"Legacy files detected in non-interactive mode"

CI 또는 비대화형 쉘에 있으며 rasen은 정리할 이전 파일을 찾았지만 프롬프트할 수 없습니다. 자동으로 승인합니다.

rasen init --force

마이그레이션 후 명령이 나타나지 않았습니다

IDE를 다시 시작합니다. 스킬은 시작 시 감지됩니다. 여전히 나타나지 않으면 rasen update를 실행하고 지원 도구에서 파일 위치를 확인합니다.

내 이전 `project.md`가 마이그레이션되지 않았습니다

의도적입니다. Rasen은 작성한 컨텍스트를 포함할 수 있으므로 절대 자동으로 project.md를 삭제하지 않습니다. 유용한 부분을 config.yaml의 context: 섹션으로 이동한 후 직접 삭제합니다. 마이그레이션 가이드는 이를 안내하며 증류하도록 AI에 전달할 수 있는 프롬프트를 포함합니다.

여전히 막혀있습니까?

Discord: discord.gg/YctCnvvshC
GitHub Issues: github.com/DumoeDss/rasen/issues
터미널에서: rasen feedback "what went wrong"이 당신을 위해 이슈를 엽니다.

문제를 보고할 때 rasen 버전(rasen --version), Node 버전(node --version), AI 도구 및 정확한 명령과 출력을 포함합니다. 도움을 훨씬 빠르게 합니다.