<p align="center">
<img src="https://raw.githubusercontent.com/agent-ix/quoin/HEAD/logo.png" alt="Quoin" width="100%" />
</p>
Quoin
Discord IX Skills
ISO/IEC/IEEE 29148
Open Knowledge Format
quoin은 ISO/IEC/IEEE 29148에 맞춰진 소프트웨어 명세서 및 기타 기술 문서를 작성하기 위한 Quire 모듈, agent 스킬, 그리고 워크플로우의 번들입니다. 이는 명세서 어휘(spec vocabulary)를 위한 사전 패키징된 모듈과, agent가 Markdown으로 직접 명세서를 작성하고 검증하는 데 필요한 아이디어 구상/작성/검토/계획 워크플로우 에이전트를 포함합니다.
quoin은 Agent-IX의 Quire 문서 표준 및 검증 엔진을 기반으로 구축되었습니다.
왜: AI agent는 코드를 빠르게 작성하지만 모호한 의도에서 벗어납니다(drift). Quoin은 명세서를 진실의 원천(source of truth)으로 만듭니다. 즉, agent가 먼저 검증되고 추적 가능한 명세서를 작성하고, 그에 기반하여 계획을 세우고 빌드합니다.
설정 (Setup)
이 플러그인이 초기화되지 않았거나 명령 실행에 실패하면, 필요한 CLI, 구성 및 로컬 진단을 위해 플러그인 설정 가이드를 따르십시오.
설정 확인 과정에서 진행을 막는 재현 가능한 Agent IX quoin 버그가 발견되면, [Agent IX Discord]에 참여하십시오. 커뮤니티 도움말은 Agent IX 제품 버그에 대한 최후의 수단이며, 로컬 자격 증명, 기계 설정, 타사 도구 또는 관련 없는 프로젝트에 대한 도움 데스크는 아닙니다. 포함해야 할 내용은 setup.md를 참조하십시오.
사용 방법 (How)
Claude Code, Codex 또는 선택한 코딩 agent에서:
1. 아이디어 구상 및 명세화 (Ideate & Specify)
아이디어를 구상한 다음 /specify로 전달합니다. 이 경우 사용자 스토리(user stories), 기능 요구사항(functional requirements), 이해관계자 요구사항(stakeholder requirements), 비기능 요구사항(non-functional requirements) 및 기타 아티팩트를 포함하는 명세서(specification)가 생성됩니다.
> /specify an electron app for tracking spice production
2. 명세서 검토 (Spec Review)
에이전트의 도움을 받아 검토하려면 /spec-review를 사용하세요. 여러 분석 작업이 병렬로 실행되며, Findings와 제안된 수정 사항이 포함된 Reviews를 출력합니다.
> /spec-review spice 생산 추적기(spice production tracker)의 명세서를 검토해 줘.
3. 계획으로 변환 (Convert to plans)
plan을 작성합니다. 이 스킬은 작업을 여러 tasks로 분해하여 plan을 만듭니다. 작성해야 할 테스트 매트릭스는 없습니다: quire matrix가 수용 기준(acceptance criteria)과 테스트의 추적 태그(trace tags)로부터 이를 계산하며, quoin matrix는 실행 증거(run evidence)를 추가합니다.
> /spec-to-plan 코딩을 위해 스파이스 추적 앱(spice tracking app)을 준비해 줘
4. 구현! (Implement!)
/implement-plan을 호출하여 코딩 에이전트가 계획에 따른 작업을 시작하도록 트리거합니다.
> /implement-plan 스파이스 추적 앱(spice tracking app) 구축해 줘
5. 격차 검토 (Gap review)
/gap-analysis는 저장소(repository)를 감사합니다: 계산된 테스트 매트릭스(quoin matrix)를 지침으로 사용하여 구현되고 테스트된 UserStory와 Functional Requirements, 그리고 역방향 격차 — 소유하는 요구사항이 없는 코드 — 와 태그가 지정된 기준 뒤에 있는 스텁(stubs)을 확인합니다. 기본적으로 계획 의존성이 없습니다(planless by default). 따라서 계획 수립 이전에 작업한 저장소도 여전히 감사할 수 있으며, 이때 방출되는 검토 기록에는 Plan completion: not assessed가 기록됩니다.
/gap-analysis는 선택적으로 spec, code, 및 tests 간의 의미론적(semantic) 비교를 수행합니다.
계획을 전달하여 완료 장부 작성(completion bookkeeping)을 추가할 수 있습니다 — 모든 완료된 Task, 의존성 순서에 따른 완료 작업, 그리고 작업 상태와 일치하는 plan.md 체크박스입니다. 저장소 감사는 이로 인해 변경되지 않습니다: 계획은 결코 범위(scope)를 좁히거나 자신의 작업을 벗어난 발견 사항을 억제하지 않습니다.
> /gap-analysis --plan Plan-001
포함된 내용 (What's included)
기본 모듈 세트는 명세 아키타입(spec archetypes)과 도메인 객체 어휘(domain-object vocabulary)를 정의합니다.
아티팩트 아키타입(Artifact archetypes) — 작성하는 문서 유형:
| Module | Archetypes |
|---|
| spec-artifacts-iso | StR, FR, NFR, US, IT, TC, Spec, master-requirements |
| ... | |
| 도메인 객체(Domain objects) — 일반적인 객체를 위한 프리팹 템플릿 | |
| Module | Objects |
|---|
| spec-objects-business | domain, entity, value_object, aggregate_root, nested_entity, repository, event, state_machine, process, enumeration |
| ... | |
에이전트 스킬 (Agent Skills)
specify: 카탈로그 작성 팩을 사용하여 명세서 파일을 생성하거나 편집하고 Quire 검증(validation)을 수행합니다.spec-review: 명세서의 품질, 일관성 및 완전성을 검토합니다.spec-matrix: 계산된 테스트 매트릭스(Test Matrix)를 읽고 각 테스트가 주장하는 기준에 태그를 지정합니다.spec-to-plan: StR/FR/NFR을 TDD 프로젝트 계획으로 변환합니다.spec-ideation: 공식적인 작성 전의 자유롭고 탐색적인 초안 작업입니다.spec-app-review / spec-object-review: 애플리케이션 명세서 및 도메인 객체 감사(audit)를 수행합니다.- 분석 렌즈(Analysis lenses): 명세서를 대상으로 하는 집중 검토 패스:
spec-integrity-analysis: 완전성, 일관성 및 원자성 품질 게이트(quality gates)spec-scope-boundary-analysis: 시스템 경계 및 책임 할당spec-dependency-analysis: 기능 구현 작업과 활성화(enablement) 작업을 분리합니다.spec-evidence-analysis: 요구사항별 검증 방법 및 증거 아티팩트(evidence artifacts)spec-failure-domain-analysis: 명시되지 않은 실패 모드, 신원 혼동, 엣지 케이스spec-risk-complexity-analysis: 작업 할당 전의 기술적 위험 및 변동성spec-security-analysis: 적용 가능한 보안 표준 및 규정 준수 추적성(compliance traceability)
설치 (Install)
quoin을 설치하는 것은 두 단계입니다. 네이티브 CLI(npm 또는 GitHub Release를 통해)와 코딩 에이전트의 스킬 및 워크플로우에 기능을 추가하는 플러그인입니다. 동일한 스킬 번들(skill bundle)은 Claude Code, OpenAI Codex, opencode, 그리고 GitHub Copilot에 설치됩니다. 아래에서 사용하려는 에이전트를 선택하세요. Anthropic API 키는 필요하지 않으며, 기존 에이전트 구독을 사용합니다.
1. CLI 설치 (quoin과 워크플로우 수명 주기 명령을 실행하는 ix-flow):
npm install -g @agent-ix/quoin @agent-ix/ix-flow@latest
@agent-ix/quoin은 사용자의 플랫폼에 맞는 네이티브 바이너리를 optionalDependency로 가져오는 런처입니다 (linux-x64, linux-arm64, darwin-arm64, win32-x64). 이 바이너리는 아래의 수동 설치에서 사용된 GitHub Release 에셋과 동일하게 빌드됩니다. 자세한 내용은 npm으로 설치하기를 참조하세요. 이후 업데이트는 npm update -g @agent-ix/quoin; quoin update를 실행하여 보고만 할 뿐, 실제 동작은 하지 않습니다. 왜냐하면 npm이 설치를 담당하기 때문입니다.
npm을 사용하지 않는 경우, 안정 버전 GitHub Release에서 호스트용 아카이브를 다운로드하고, quoin-update-manifest.json으로 검증한 다음, quoin을 추출하여 PATH에 배치합니다. 이후 quoin update가 나중에 업데이트하는 것을 자체적으로 관리합니다. 지원되는 네이티브 대상 및 아카이브 이름은 네이티브 릴리스 계약에 나와 있습니다.
2. 플러그인을 코딩 에이전트에 추가하기:
<details>
<summary><b>Claude Code</b></summary>
다음 명령어를 Claude Code 내에서 실행하세요:
/plugin marketplace add agent-ix/agent-plugins
/plugin install quoin@agent-ix
</details>
<details>
<summary><b>OpenAI Codex</b></summary>
codex plugin marketplace add agent-ix/agent-plugins
codex plugin add quoin@agent-ix
또는 Codex TUI의 /plugins 메뉴에서 quoin을 찾아 설치하세요.
</details>
<details>
<summary><b>opencode</b></summary>
GitHub CLI를 사용하여 스킬을 설치합니다. --all은 전체 번들을 설치하고, --scope user는 모든 리포지토리에서 사용 가능하게 만듭니다:
gh skill install agent-ix/quoin --all --scope user --agent opencode
</details>
<details>
<summary><b>GitHub Copilot</b></summary>
Copilot CLI를 사용하는 경우:
copilot plugin marketplace add agent-ix/quoin
copilot plugin install quoin@quoin
또는 GitHub CLI로 스킬을 설치합니다:
gh skill install agent-ix/quoin --all --scope user --agent github-copilot
</details>
어떤 방법을 사용하든, 이는 quoin의 명세 작성(spec-authoring) 스킬과 워크플로우를 등록하여 에이전트에게 요청함으로써 이를 구동할 수 있게 합니다.
사용법
스킬 및 워크플로우
사용자가 명세서를 작성하는 주요 방법은 에이전트에게 요청하여, 번들된 skills와 workflows를 호출하게 하는 것입니다.
CLI 명령어
명세서 어휘(vocabulary)를 검사하고 설치된 모듈을 관리하세요:
quoin catalog list
quoin catalog show FR
quoin catalog validate
...
Quoin은 또한 권한 안전성(rights-safe)의 프로젝트 소유형 보증 워크플로우를 제공합니다: Quire로 일반적인 ClauseSet을 평가하고, 점수 없이 해제(discharge)를 처리하며, 명시적인 충분성 결정(sufficiency decisions)이 포함된 작성된 주장(authored argument)을 렌더링하고, 변경 불가능한 실험 또는 운영 증거를 게시할 수 있습니다:
quire clauses evaluate --module ./modules/widget --authority example.invalid \
--set widget-rules --version 1.0.0 \
--context product=widget --format json > binding.json
...
레코드 형태(record shapes), 만료 동작(expiry behavior), 그리고 기존 실행 레코드를 변경하지 않는 경계에 대해서는 Assurance workflows를 참조하세요.
일반적인 측정 캠페인(measurement campaigns)은 작성된 절차(authored procedure) 각각을 Engineering Assurance의 제한된 실행기(bounded executor)를 통해 실행하고, 별도로 재실행 가능한 판결(verdict)을 유지합니다:
quoin measurement campaign run --repo /path/to/clean-measured-checkout \
--definition /path/to/campaign-definition.json --run-id trial-1 \
--config /path/to/campaign-run-config.json
...
정의는 측정된 체크아웃 외부에서 존재할 수 있어, 자기 참조적인 Git 커밋 없이 더 이른 소스 리비전(source revision)을 고정(pin)할 수 있게 합니다. 실행 구성(run config)은 quoin.campaign-run-config/v1을 사용하며, 정확한 클린 소스 체크아웃, 프로듀서 및 체커 실행 파일, 런타임 바인딩을 선택합니다. 검증(Verification)은 보존된 증거와 동일하게 고정된 소스 리비전을 다시 엽니다. 멤버 의존성(Member dependencies)은 순서 지정과 완료가 필요합니다. Quoin은 모든 선택된 프로듀서 입력 바이트 문자열을 다이제스트(digest)로 유지하고, 기록된 소스 파일 또는 의존성 아티팩트의 출처를 정확한 Git 트리 또는 더 이른 EA 결과와 독립적으로 재실행(replay)합니다. 작성된 절차(authored procedure)가 inputOrigins를 선언할 때, EA는 일치하지 않는 런타임 선택을 거부하고 Quoin은 모든 선언된 역할을 매칭한 후에만 보존된 인벤토리(inventory)를 enforced(강제됨)로 표시합니다. 해당 선언이 없는 이전 절차들은 작성된 출처 보증을 위해 명시적으로 unclaimed(미청구됨) 상태로 남아 있으며, 선택된 바이트와 기록된 출처는 여전히 재실행 검사(replay-checked)를 거칩니다. 도메인 체커(domain checker)가 해당 입력들의 측정별 의미를 해석합니다.
개발 (Development)
make rust-build
make rust-test
make rust-lint
명세 (Specification)
이 라이브러리의 기술 명세(technical specification)는 그 자체로 spec-artifacts-iso 모듈을 사용하여 작성되었으며, spec/spec.md를 참조하십시오.
소개 (About)
quoin은 다음 핵심 라이브러리들 위에 구축된 Agent-IX 생태계의 일부입니다:
