Viserys란 무엇인가요?
Viserys는 AI 코딩 에이전트를 위한 독립형 엔지니어링 워크플로 모음입니다. 에이전트가 모든 요청에 대해 매번 프로세스를 임의로 만들도록 하는 대신, 재사용 가능한 Markdown 지침, 리뷰어 페르소나, 공용 참조 자료, 수명 주기 명령, 평가 픽스처, 검증 스크립트를 제공합니다.
이 프로젝트는 소프트웨어 작업을 다음 6단계 수명 주기로 구성합니다.
DEFINE -> PLAN -> BUILD -> VERIFY -> REVIEW -> SHIP각 워크플로는 SKILL.md 파일에 있으며, 절차 단계, 종료 기준, 합리화 방지 지침을 포함합니다. 스킬은 일반 Markdown으로 작성되므로 스킬을 인식하는 코딩 에이전트가 불러오거나 독립적인 지침으로 직접 읽을 수 있습니다.
주요 기능
- 수명 주기 전반 지원: 요구 사항, 계획 수립, 구현, 테스트, 리뷰, 릴리스 준비를 다루는 워크플로를 제공합니다.
- 26개의 패키지 스킬:
skills/디렉터리에 재사용 가능한 엔지니어링 워크플로가 포함되어 있습니다. - 리뷰어 페르소나: 전문 에이전트가 코드 품질, 테스트, 보안, 웹 성능을 평가합니다.
- OpenCode 통합: 기본 모드의 Viserys 에이전트가 포함되어 있으며 전역 설정 없이 스킬을 불러옵니다.
- 공용 참조 자료: 체크리스트를 에이전트 컨텍스트에 영구적으로 배치하지 않고 필요할 때 불러올 수 있습니다.
- 검증 및 평가: Node.js 스크립트가 스킬, 명령, 아티팩트 경로, 참조 링크, 버전, 평가 사례를 확인합니다.
저장소 구조 이해하기
skills/에는 스킬 워크플로가 있습니다.agents/에는 4개의 전문 리뷰어 페르소나가 있습니다.references/는 필요할 때 불러오는 공용 체크리스트를 제공합니다.commands/에는 수명 주기 명령이 정의되어 있습니다.evals/에는 스킬 평가 사례와 픽스처가 있습니다.scripts/에는 검증 도구와 평가 실행기가 있습니다.hooks/는 세션 수명 주기 훅을 제공합니다.docs/에는 내부 문서가 있습니다..opencode/agent/viserys.md는 OpenCode 에이전트를 정의합니다..opencode/opencode.json은 OpenCode에 스킬 경로를 등록합니다.
설치 및 설정
옵션 1: OpenCode에서 Viserys 활성화
- Git으로 Viserys 저장소를 클론합니다.
- OpenCode에서 클론한 저장소 폴더를 엽니다.
Tab을 눌러 에이전트 선택기를 엽니다.viserys를 선택합니다.
포함된 Viserys 에이전트는 기본 모드로 실행되므로 OpenCode의 에이전트 목록에 표시됩니다. 이 에이전트의 프롬프트는 요청을 처리하기 전에 적용 가능한 스킬이 있는지 확인하고, 프로젝트 수명 주기에 따라 작업을 진행합니다. 저장소 수준의 OpenCode 설정에 모든 패키지 스킬이 등록되어 있으므로 전역 설정이 필요하지 않습니다.
옵션 2: 다른 스킬 인식 에이전트에서 Viserys 사용
Claude Code, Cursor 또는 재사용 가능한 스킬을 지원하는 다른 에이전트에서는 에이전트가 저장소의 skills/ 디렉터리를 참조하도록 설정합니다. 또는 해당 디렉터리를 도구의 기본 스킬 위치에 복사합니다.
정확한 대상 위치는 코딩 에이전트에 따라 다릅니다. Viserys의 Markdown 워크플로를 다른 형식으로 변환할 필요는 없지만, 호스트 도구가 스킬을 검색할 위치를 알고 있어야 합니다.
옵션 3: 스킬을 일반 컨텍스트로 사용
에이전트에 기본 스킬 시스템이 없다면 관련 SKILL.md 파일을 열고 그 내용을 컨텍스트로 제공합니다. 모든 스킬은 독립적으로 작동하도록 설계되었으므로 단계를 직접 따르거나 에이전트가 따르도록 지시할 수 있습니다.
적절한 워크플로 선택하기
어떤 워크플로를 적용해야 할지 확실하지 않다면 메타 스킬인 using-agent-skills부터 시작합니다. 그렇지 않다면 현재 수명 주기 단계에 맞는 스킬을 선택합니다.
DEFINE: 작업 명확히 하기
- 개념이 모호하고 체계적인 탐색이 필요할 때는
idea-refine을 사용합니다. - 요구 사항을 한 번에 한 질문씩 수집해야 할 때는
interview-me를 사용합니다. - 사양 없이 프로젝트, 기능 또는 중요한 변경을 시작하기 전에는
spec-driven-development를 사용합니다. - 품질 기준이 없거나 단순히 빌드를 통과시키기 위해 검사를 억제하고 있을 때는
constraint-driven-development를 사용합니다.
PLAN: 사양을 작업으로 전환하기
요구 사항이 안정되면 planning-and-task-breakdown을 사용합니다. 이 스킬은 사양을 수용 기준이 포함된 순서화되고 검증 가능한 작업으로 변환합니다.
BUILD: 신중하게 구현하기
incremental-implementation은 여러 파일에 걸친 변경 사항을 작은 단위로 나누어 반영하도록 돕습니다.- 로직을 구현하거나 버그를 수정하거나 동작을 변경할 때는
test-driven-development를 적용합니다. - 세션을 초기화하거나 작업을 전환하거나 출력 품질이 저하될 때는
context-engineering이 도움이 됩니다. - 정확성이 최신 공식 문서에 달려 있을 때는
source-driven-development가 적합합니다. - 중요도가 높고 지금 확인하는 비용이 나중에 디버깅하는 비용보다 저렴할 때는
doubt-driven-development가 검증을 촉진합니다. frontend-ui-engineering은 사용자 대상 인터페이스 작업을 안내합니다.api-and-interface-design은 API, 모듈 경계, 공개 인터페이스 설계를 지원합니다.
VERIFY: 변경 사항이 작동함을 입증하기
- 브라우저 기반 구현이나 디버깅에는
browser-testing-with-devtools를 사용합니다. - 테스트가 실패하거나 빌드가 중단되거나 런타임 동작이 예상과 다를 때는
debugging-and-error-recovery를 사용합니다.
REVIEW: 품질과 위험 평가하기
- 변경 사항을 병합하기 전에
code-review-and-quality를 사용해야 합니다. - 작동하는 코드가 여전히 이해하거나 유지 관리하기 어려울 때
code-simplification이 유용합니다. - 사용자 입력, 인증, 데이터 저장 및 외부 통합에는
security-and-hardening을 적용합니다. - 성능 요구 사항이 있거나 성능 저하가 의심될 때
performance-optimization을 적용합니다.
SHIP: 프로덕션 준비
git-workflow-and-versioning은 코드 변경과 버전 관리를 안내합니다.ci-cd-and-automation은 빌드 및 배포 파이프라인 변경을 지원합니다.deprecation-and-migration은 기존 시스템을 제거하거나 사용자를 마이그레이션하는 데 도움을 줍니다.documentation-and-adrs는 아키텍처 결정과 공개 API 변경 사항을 기록합니다.observability-and-instrumentation은 로그, 메트릭, 트레이스 및 알림을 다룹니다.shipping-and-launch는 최종 프로덕션 배포 준비를 안내합니다.
기본 사용 예시
AI 코딩 에이전트에게 인증된 새 API 엔드포인트를 추가하도록 요청한다고 가정해 보겠습니다. 바로 구현에 들어가는 대신 라이프사이클을 순서대로 적용합니다.
- 정의: 인증 규칙, 입력 또는 응답이 명확하지 않다면
interview-me를 실행합니다. 그런 다음spec-driven-development를 사용해 예상 동작을 정립합니다. - 계획:
planning-and-task-breakdown을 적용해 작업 순서와 수용 기준을 작성합니다. - 구현: 엔드포인트 계약에는
api-and-interface-design을, 동작 구현에는test-driven-development를 사용합니다. 여러 파일을 변경해야 한다면incremental-implementation도 사용합니다. - 검증: 테스트가 실패하거나 엔드포인트가 예상과 다르게 동작하면
debugging-and-error-recovery를 따릅니다. - 검토: 이 기능은 인증과 입력을 처리하므로
code-review-and-quality와security-and-hardening을 적용합니다. - 배포: 프로덕션에 배포하기 전에 적절한 Git, 문서화, 관측성 및 출시 워크플로를 사용합니다.
OpenCode 통합이 활성화되면 Viserys 에이전트는 먼저 일치하는 스킬을 확인하도록 설계되어 있습니다. 일반 컨텍스트 설정에서는 직접 스킬을 선택하고 에이전트에게 선택한 각 Markdown 워크플로를 따르도록 요청합니다.
리뷰어 페르소나 사용
Viserys에는 agents/에 네 가지 리뷰어 페르소나가 포함되어 있습니다. 이들은 라이프사이클 스킬을 보완하는 집중된 관점을 제공합니다.
agents/code-reviewer.md는 스태프 엔지니어의 승인 기준에 따라 다섯 가지 축으로 리뷰를 수행합니다.agents/test-engineer.md는 prove-it 패턴을 사용해 테스트 전략과 커버리지를 검토합니다.agents/security-auditor.md는 취약점 탐지, 위협 모델링 및 OWASP 평가를 다룹니다.agents/web-performance-auditor.md는 빠른 모드 또는 심층 모드로 Core Web Vitals를 감사합니다.
변경 사항의 위험에 따라 페르소나를 선택합니다. 예를 들어 인증 작업에는 보안 감사자를 security-and-hardening과 함께 사용하고, 사용자에게 보이는 인터페이스를 수정한 후에는 웹 성능 감사자를 사용할 수 있습니다.
워크플로 팩 검증
스킬, 명령, 참조, 버전 또는 평가 픽스처를 변경한 후 제공된 Node.js 스크립트를 실행합니다.
node scripts/validate-skills.js
node scripts/validate-commands.js
node scripts/validate-artifact-paths.js
node scripts/validate-reference-links.js
node scripts/validate-versions.js
node scripts/run-evals.js이 명령은 팩의 내부 구조를 검증하고 평가 스위트를 실행합니다. 기존 워크플로를 단순히 사용하는 것이 아니라 Viserys를 확장할 때 특히 중요합니다.
고급 팁
라이프사이클 게이트를 건너뛰지 않고 스킬 조합하기
작업에 둘 이상의 스킬이 필요할 수 있습니다. 예를 들어 브라우저 기능은 frontend-ui-engineering, test-driven-development 및 browser-testing-with-devtools를 조합할 수 있습니다. 각 스킬의 종료 기준을 명확히 유지하여 워크플로를 추가하더라도 구조 없는 프롬프트가 되지 않도록 합니다.
필요할 때만 참조 자료 로드하기
references/ 디렉터리는 필요할 때 로드하는 공유 체크리스트를 위한 공간입니다. 이를 통해 에이전트의 활성 컨텍스트를 집중된 상태로 유지하면서도 상세한 지침에 접근할 수 있습니다.
버전에 민감한 작업에는 공식 출처 사용하기
구현 세부 사항이 최신 문서에 따라 달라질 때는 source-driven-development를 적용합니다. 그럴듯하지만 잘못된 가정의 비용이 클 때는 doubt-driven-development와 함께 사용합니다.
에이전트 품질이 저하될 때 복구하기
긴 세션에서 일관성이 떨어지면 context-engineering을 사용합니다. 이 스킬은 세션 설정, 작업 전환 및 출력 품질이 저하된 상황을 위해 특별히 마련되었습니다.
포함된 문서 참고하기
docs/README.md는 팩과 라이프사이클 지도를 설명합니다.docs/skill-anatomy.md는SKILL.md형식을 정의합니다.evals/README.md는 스킬 평가 방식을 설명합니다.
워크플로를 추가하거나 재구성하기 전에 스킬 구조 사양을 읽은 다음, 검증기와 평가를 실행해 결과를 확인합니다.
결론
Viserys는 AI 지원 개발을 반복 가능한 엔지니어링 프로세스로 전환합니다. 먼저 skills/ 디렉터리를 호환되는 에이전트에 연결하거나 OpenCode에서 번들로 제공되는 Viserys 에이전트를 선택합니다. 그런 다음 DEFINE, PLAN, BUILD, VERIFY, REVIEW 및 SHIP을 차례로 진행하고, 도움이 되는 경우 전문 페르소나와 검증 스크립트를 사용합니다.