범용 개발 표준
npm version
License: MIT + CC BY 4.0
Node.js
언어: 영어 | 繁體中文 | 简体中文
버전: 6.15.0 | 릴리스일: 2026-11-04 | 라이선스: Dual License (CC BY 4.0 + MIT)
소프트웨어 프로젝트를 위한 언어에 구애받지 않고(Language-agnostic), 프레임워크에 구애받지 않는(framework-agnostic) 개발 표준입니다. AI 네이티브 워크플로우를 통해 다양한 기술 스택 전반에 걸쳐 일관성, 품질 및 유지보수성을 보장합니다.
🚀 빠른 시작 (Quick Start)
npm을 통한 설치 (권장)
npm install -g universal-dev-standards
...
베타 또는 RC 버전을 찾으시나요? Pre-release Versions를 확인하십시오.
또는 npx 사용 (설치 불필요)
npx universal-dev-standards init
참고: 표준만 복사하는 것으로는 AI 지원이 활성화되지 않습니다. AI 도구를 자동으로 구성하려면 uds init을 사용하거나, 수동으로 도구의 설정 파일에 표준을 참조하십시오.
🗺️ 다음 단계 (What's Next?)
| 원하는 작업 | 명령어 |
|---|
| 기존 코드베이스 이해하기 | /discover |
| ... | |
팁: 모든 개발 단계 및 사용 가능한 명령에 대한 전체 가이드는 /dev-workflow를 입력하십시오.
또한 보기: Daily Workflow Guide
📚 문서 (Documentation)
✨ 기능 (Features)
<!-- UDS_STATS_TABLE_START -->
| 카테고리 | 개수 | 설명 |
|---|
| 핵심 표준 | 153 | 범용 개발 가이드라인 |
| ... | <!-- UDS_STATS_TABLE_END --> | |
5.0에서 새로운 기능은? 자세한 내용은 Pre-release Notes를 확인하십시오.
🏗️ 아키텍처 (Architecture)
UDS 콘텐츠는 **두 개의 독립적인 축(two independent axes)**을 따라 구성되어 있습니다. 이들은 서로 다른 질문에 답하며, 이를 혼동하는 것이 레이아웃을 잘못 이해하는 가장 흔한 방식이므로 별도로 명시됩니다.
축 1 — 깊이 (Depth): 항상 로드되어야 하는 양
이 축은 **행동 계약(behavioural contract)**입니다. AI 에이전트에게 무엇을 선제적으로 읽어야 하고, 무엇은 요청할 때까지 남겨두어야 하는지 알려줍니다. 이는 컨텍스트 비용(context cost)에 중요한 영향을 미치는 축입니다.
graph TD
A[AI 에이전트 / 개발자] --> R["<b>규칙(Rules)</b><br/>core/*.md<br/><b>항상 읽기(Always Read)</b>"]
R -- "설명이나 작업 예시가 필요할 때" --> G["<b>가이드(Guides)</b><br/>core/guides/*.md<br/>요청 시에만 읽기(Read on Demand Only)]
...
| 레이어 | 위치 | 포함 내용 | AI 행동 방식 |
|---|
| 규칙 (Rules) | core/*.md | 실행 가능한 규칙, 체크리스트, 임계값 | 항상 읽기 |
| ... | | | |
이 축은 깊이에 대한 주장(depth claim)을 포함하지 않습니다. 표준의 .ai.yaml과 .md 형태는 누가 읽느냐에 따라 선택된, 동일한 자료를 담는 두 가지 인코딩 방식입니다.
| 측면 | ai/standards/*.ai.yaml | core/*.md |
|---|
| 인코딩 | 구조화된 YAML (Structured YAML) | 산문형 마크다운 (Prose Markdown) |
| ... | | |
| <sup>†</sup> 측정일 2026-07-23 기준, 두 가지 형태를 모두 가진 135개 표준을 통해 측정: YAML은 872,380 바이트, 마크다운은 1,271,471 바이트입니다. Content Architecture §7의 명령어를 사용하여 재현할 수 있습니다. | | |
📐 통합 전반에 걸쳐 적용되는 깊이 계약과 해당 계약과 현재 트리 간의 측정된 격차는 **docs/reference/CONTENT-ARCHITECTURE.md**에 문서화되어 있습니다.
🤖 AI 도구 지원
UDS는 11개의 라이브 도구(live tools) 통합을 제공합니다. 이 중 1개는 행동적으로 검증되었습니다.
이 두 가지는 의도적으로 다른 수치입니다. **상태(Status)**는 우리가 작성한 통합의 완성도를 나타냅니다. **검증됨(Verified)**은 누군가 해당 도구가 실제로 이를 읽고 적절하게 작동하는지, 즉 프로브(probes)를 실행하고 출력을 기록함으로써 확인했는지 여부를 의미합니다. 오늘까지 이 두 번째 질문은 한 번도 제기된 적이 없었으므로, 이에 대한 답변을 가정할 수 없습니다. 프로브 설계와 검증 대기열(verification queue)에 대해서는 XSPEC-357을 참조하십시오 (Antigravity → Codex → Claude Code → 나머지).
| AI 도구 | 상태 (Status) | 검증됨 (Verified) | 스킬 (Skills) | 슬래시 명령어 (Slash Commands) | 설정 (Configuration) |
|---|
| Claude Code | ✅ 완료 (Complete) | 🔬 —<sup>◆</sup> | 55 | 51 | CLAUDE.md |
| ... | | | | | |
상태 범례 (우리가 작성한 통합의 완성도):
✅ 완료(Complete) | 🔶 부분적(Partial) | ⚠️ 최소(Minimal) | ⏳ 계획 중(Planned) | ⛔ 단종(Discontinued)
검증됨 범례 (프로브 실행이 도구가 적절하게 작동했는지 확인했는지 여부):
✅ 날짜 검증 완료(verified) | 🔬 — 아직 검증되지 않음(not yet verified) | ⌛ 만료(expired) | ❌ 실패(failed)
<sup>◆</sup> Claude Code는 유지 관리자에 의해 매일 프로덕션 환경에서 사용되고 있기 때문에 통합이 가장 완성도가 높습니다. 하지만 일상적인 사용은 기록된 검증을 의미하지 않으며, 도구 스스로를 판단할 수는 없습니다. 이 역시 다른 모든 것들과 마찬가지로 대기열에 있습니다.
<sup>†</sup> 구글(Google)은 2026-06-18에 Gemini CLI를 단종(sunset)했습니다 (I/O 2026-05-19에서 발표, 30일 마이그레이션 기간). 이후 Antigravity CLI가 그 자리를 이어받았습니다. integrations/gemini-cli/ 및 .gemini/ 디렉터리는 동결(frozen) 상태입니다. 참고용으로 보관되며 동기화 검사에서는 제외되고 더 이상 유지 관리되지 않습니다. .gemini/DEPRECATED.md를 참조하십시오.
<sup class="‡">‡</sup> Antigravity는 스킬(skills)을 지원하지만, 실제 Antigravity CLI를 기준으로 올바른 설치 경로는 아직 검증되지 않았습니다. 두 가지 후보가 충돌합니다: ~/.gemini/antigravity-cli/plugins/<name>/skills/ (공식 플러그인 문서)와 .agent/skills/ (UDS 자체 2026-02 사양, Gemini CLI 시대에 작성됨). 따라서 uds init은 이 타겟에 대한 스킬을 하나로 확정될 때까지 설치하지 않습니다. 검증되지 않은 경로는 조용히 실패하므로, 아예 설치하지 않는 것보다 더 나쁩니다.
📦 설치 방법 (Installation Methods)
npm (권장)
npm install -g universal-dev-standards
uds init
uds check
...
⚙️ 설정 (Configuration)
uds config를 사용하여 환경 설정을 관리하세요:
| 매개변수 (Parameter) | 명령어 (Command) | 설명 (Description) |
|---|
| 커밋 언어 (Commit Language) | uds config set output_language traditional-chinese | AI 커밋의 기본 언어를 설정합니다. |
| ... | | |
👥 기여하기 (Contributing)
- 개선 사항 제안: 문제점과 해결책을 포함하여 이슈를 여세요.
- 예제 추가: 실제 사용 사례 예제를 제출하세요.
- 표준 확장: 언어/프레임워크 확장에 기여하세요.
자세한 지침은 CONTRIBUTING.md를 참조하세요.
📄 라이선스 (License)
| 구성 요소 (Component) | 라이선스 (License) | |
|---|
| 문서화 (Documentation) | CC BY 4.0 | |
| CLI 도구 (CLI Tool) | MIT | |
감사의 글 (Acknowledgments)
UDS는 다음의 뛰어난 오픈 소스 프로젝트들로부터 아키텍처 영감을 얻었습니다:
| 프로젝트 (Project) | 영감 출처 (Inspiration) | 라이선스 (License) |
|---|
| Superpowers | 체계적인 디버깅, 에이전트 전송(agent dispatch), 검증 증거 (verification evidence) | MIT |
| ... | | |
참고: UDS는 개념과 방법론만을 채택하며, 이 프로젝트들로부터의 소스 코드는 포함하지 않습니다.
오픈 소스 커뮤니티가 ❤️로 유지보수합니다
