프로젝트 구성
config.yaml에 몇 줄만 작성하여 워크플로가 원하는 방식으로 변경 사항을 계획하도록 설정하세요.
openspec/config.yaml은 변경 사항이 어떤 방식으로 계획되기를 원하는지 워크플로에 알려 줍니다.
예를 들어, 다음 구성은 tasks.md 아티팩트의 생성 규칙을 업데이트합니다:
rules:
tasks:
- End every task with a commit에이전트가 실행되면 이 규칙을 참조하여 모든 작업이 커밋 단계로 끝나도록 합니다.
규칙은 짧게 유지하세요. 여기에 있는 모든 내용은 에이전트의 컨텍스트에 포함되며, 장황한 규칙은 출력을 더 나쁘게 만들 수 있습니다.
작동 방식
config.yaml에는 에이전트가 아티팩트를 생성하거나 워크플로를 진행할 때 받는 지침이 담겨 있습니다.
실행할 때마다 다음과 같은 일이 발생합니다:
- 워크플로를 실행합니다(예:
/openspec-propose). - 에이전트가
openspec instructions명령을 호출합니다. - 이 명령은 config.yaml에서 컨텍스트와 규칙을 읽습니다.
- OpenSpec의 내장 지침과 사용자 정의 내용이 에이전트를 위한 하나의 프롬프트로 결합됩니다.
- 에이전트는 해당 프롬프트를 따라 아티팩트를 작성합니다.
예를 들어, context 필드와 이 페이지 상단의 규칙이 있을 때 openspec instructions가 tasks.md에 대해 반환하는 내용은 다음과 같습니다(일부 생략 및 주석 추가):
<artifact id="tasks" change="add-dark-mode" schema="spec-driven">
<!-- config.yaml에서: context -->
<project_context>
Designs and tasks must cover Windows, macOS, and Linux
Write all artifacts in Spanish
</project_context>
<!-- config.yaml에서: tasks에 대한 규칙 -->
<rules>
- End every task with a commit
</rules>
<!-- OpenSpec에서: 내장 지침 -->
<instruction>
...how to write a good tasks.md...
</instruction>
<template>
...the tasks.md structure to fill in...
</template>
</artifact>설정 내용이 먼저 전달되고, 그다음 OpenSpec의 내장 지침과 템플릿이 전달됩니다. 규칙은 내장 지침에 추가되며 절대 대체하지 않습니다. config.yaml 수정 사항은 다음 실행 시 에이전트에 반영됩니다.
필드
세 가지 필드가 에이전트가 받는 내용을 형성합니다. 각 필드의 정확한 계약(유형, 제한, 유효성 검사)은 프로젝트 구성(config.yaml)에 나와 있습니다.
| 필드 | 역할 | 주입 대상 |
|---|---|---|
context | 에이전트가 항상 받는 지침 | 모든 대상: 모든 아티팩트, apply, archive |
rules | 하나의 아티팩트에 대한 추가 지침 | 해당 아티팩트 생성 시에만 |
operations | 워크플로 단계 수행 방식에 대한 지침 | apply 및 archive에만 |
config.yaml의 다른 필드(schema, store, references)는 프로젝트가 사용할 스키마와 OpenSpec 루트를 선택합니다. 계약 페이지에서 이들 필드를 다룹니다.
마지막 열은 정확하므로, 필드는 거기에 나열된 단계에만 전달됩니다. 특히 verify는 rules를 받지 않습니다. verify는 작성된 아티팩트를 기준으로 구현을 검사합니다.
context
context는 에이전트가 아티팩트를 생성하거나 작업을 적용하거나 변경 사항을 아카이브할 때 받는 배경 정보입니다.
context: |
We ship cross-platform. Designs and tasks must cover Windows, macOS, and Linux
Write all artifacts in Spanish워크플로 출력에 반영되어야 하는 사실과 제약 조건에는 context를 사용하세요. 지속적으로 유지할 프로젝트 문서는 프로젝트의 문서 파일에 두고, 에이전트가 코드를 읽어 알 수 있는 내용은 제외하세요.
다른 언어: context는 모든 아티팩트에 전달되므로, Write all artifacts in Spanish.를 추가하여 에이전트가 proposal, spec, design, tasks 아티팩트를 스페인어로 작성하도록 지시할 수 있습니다.
rules
rules는 아티팩트 id를 키로 하여 하나의 아티팩트에 연결됩니다. 각 줄은 해당 아티팩트의 내장 지침에 추가됩니다:
rules:
proposal:
- Keep proposals under 500 words
tasks:
- Every UI task includes a Playwright test이제 제안서는 짧게 유지되고 tasks.md는 항상 브라우저 테스트를 계획합니다. 다른 모든 아티팩트는 그대로 유지됩니다.
operations
operations는 아티팩트에 기록되는 내용이 아니라, 에이전트가 apply와 archive를 수행하는 방식을 안내합니다:
operations:
apply:
guidance:
- Run the linter before marking a task complete
archive:
guidance:
- Summarize what shipped before archivingapply 중에는 에이전트가 작업을 완료할 때마다 린트를 실행합니다. archive 중에는 요약으로 마무리합니다.
config.yaml만으로 충분하지 않을 때
구성은 표준 워크플로 위에 지침을 추가하지만, 어떤 아티팩트가 존재하는지 또는 어떻게 구조화되는지는 변경할 수 없습니다. 그 수준의 제어가 필요하거나 규칙이 동작을 일관되게 이끌지 못할 때는 스키마를 포크하세요.