🛡️ DocGuard
English · Português (BR) · Español
명세 기반 개발(Spec-Driven Development)을 위한 강제 구현 계층입니다.
검증합니다. 점수를 매깁니다. 강제 적용합니다. AI 에이전트가 실제로 사용할 수 있는 문서를 배포하세요.
CI
npm
npm downloads
PyPI
License: MIT
Node.js
Runtime deps
Spec Kit Extension
Glama
MCP Registry
✨ DocGuard가 30초 만에 무엇을 잡아내는지 확인해 보세요 — 설치나 설정이 필요 없습니다:
의도적인 이탈(intentional drift)이 있는 내장 샘플 프로젝트를 대상으로 실행되며, 발견된 문제점과 이를 수정할 명확한 경로를 보여줍니다.
DocGuard demo
📚 문서화: 설치(Installation) · 기존 프로젝트(Existing projects) · Spec Kit · CI · 언어 및 프레임워크(Languages and frameworks) · 코딩 에이전트(Coding agents) · 발견된 코드(Finding codes) · 문제 해결(Troubleshooting)
목차
⚠️ [IMG:N] 형식 토큰은 이미지 placeholder 입니다. 번역하지 말고 원래 위치에 그대로 유지하세요.
DocGuard란 무엇인가요? (What is DocGuard?)
DocGuard는 **캐노니컬 기반 개발(Canonical-Driven Development, CDD)**을 강제합니다. 이는 문서가 사후적인 추가물이 아니라 진실의 원천(source of truth)이 되는 방법론입니다. AI가 문서를 작성하면, DocGuard가 이를 검증합니다.
| 전통적 개발 (Traditional Development) | 캐노니컬 기반 개발 (Canonical-Driven Development) |
|---|
| 코드 우선, 문서는 선택 사항 | 문서 우선, 코드가 따름 |
| ... | |
| DocGuard는 공식 GitHub Spec Kit 커뮤니티 확장 기능입니다. 이는 Spec Kit이 생성하는 아티팩트를 검증하여 개발 수명 주기 전반에 걸쳐 명세(specs)의 품질을 유지하도록 보장합니다. | |
🧭 작동 방식 (10페이지 브리프) (PDF) · 📖 철학 (Philosophy) · 📋 CDD 표준 (CDD Standard) · ⚖️ 비교 분석 (Comparisons) · 🔬 검증 (Validation) · 🗺️ 로드맵 (Roadmap)
아키텍처 (Architecture)
graph TD
CLI[
DocGuard는 선언된 문서화 사실을 리포지토리 증거와 비교하고 에이전트에게 구조화된 복구 작업을 제공합니다. 결정론적(Deterministic) 검사는 지원되는 사실, 참조, 그리고 생성된 섹션을 다룹니다. 인간이 작성한 요구 사항과 아키텍처 결정은 구현이 벗어날 때도 그 권위를 유지합니다.
가드(Guard) 결과는 수행된 검사를 설명합니다. CDD 등급은 구조적 성숙도를 측정합니다. `.docguard-evidence.json`의 정확한 선언을 통해 선택된 진술들을 현재 로컬 증거와 검증할 수 있으며, 나머지 모든 진술은 미검증 상태로 남습니다. 커버리지(Coverage) 및 해결되지 않은 주장들은 계속 표시되므로, 팀은 적절한 강제 정책을 선택할 수 있습니다.
연구는 이 접근 방식의 평가를 촉진합니다. 2026년 연구에 따르면 리포지토리 컨텍스트 파일이 일반적으로 작업 성공률을 개선하지 못했으며, 평가된 환경에서 추론 비용(inference cost)을 증가시킨 것으로 나타났습니다. 또한 에이전트들이 전반적으로 지침을 따랐다는 것도 발견했습니다. 이러한 결과는 간결하고 관련성 높은 컨텍스트를 테스트하고 실제 작업 결과를 측정하는 것을 뒷받침할 뿐, DocGuard의 효과성을 확립하지는 않습니다. [Evaluating AGENTS.md, 2026년 6월 수정](https://arxiv.org/abs/2602.11988v2).
[현재 로드맵](https://github.com/raccioly/docguard/blob/main/ROADMAP.md)은 정확한 탐지, 재현 가능한 증거, 문서 라이프사이클 관리(document lifecycle management), 그리고 기여자 제공 회귀 케이스(regression cases)를 우선순위로 둡니다. 출시된 계획과 대체된 사양들은 활성 AI 컨텍스트에서 제거되며 Git으로부터 복구 가능하게 유지됩니다.
---
## ⚡ 빠른 시작하기
> **패키지 명명 규칙:** 이 레포는 `raccioly/docguard`이며, 게시되는 패키지는 [npm](https://www.npmjs.com/package/docguard-cli)과 [PyPI](https://pypi.org/project/docguard-cli/) 모두에서 **`docguard-cli`**입니다. 설치된 명령어는 `docguard`입니다. 같은 프로젝트이지만, `-cli` 접미사는 단지 레지스트리 이름일 뿐입니다. 이 패키지는 **설치 스크립트를 실행하지 않으므로**, `npm i -g docguard-cli --ignore-scripts`와 동일합니다.
### Node.js (npm)
```bash
# 설치 불필요 — 직접 실행
npx docguard-cli diagnose
...
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
Python (PyPI)
pip install docguard-cli
docguard diagnose
참고: 이 Python 패키지는 npx로 위임하는 얇은 Wrapper입니다. 시스템에는 Node.js 18 이상이 필요합니다.
Docker (MCP 서버)
MCP 서버는 GHCR에 컨테이너 이미지 형태로 제공되므로, Node.js 설치가 필요 없습니다. 공개 이미지이기 때문에 풀(pull)할 때 인증이 필요하지 않습니다:
docker run -i --rm -v "$PWD":/workspace ghcr.io/raccioly/docguard:latest
진입점(entrypoint)은 stdio MCP 전송 방식입니다. stdout이 JSON-RPC 채널이므로, 다른 모든 출력을 이 채널에서 제외해야 합니다. 검사하려는 프로젝트를 /workspace에 마운트합니다. 도구들은 기본적으로 이를 검사하며, 도구 호출의 projectDir은 /workspace 또는 그 내부 디렉터리여야 합니다 (다른 마운트된 트리를 제공하려면 이미지 이름 뒤에 --root <dir>을 추가하십시오).
CI에서 latest를 추적하기보다 버전을 고정하는 것이 좋습니다:
docker run -i --rm -v "$PWD":/workspace ghcr.io/raccioly/docguard:0.34.9
서버는 **읽기 전용(read-only)**입니다: 마운트된 프로젝트만 읽습니다.
통합 방법 추가
- pre-commit — 커밋 시마다 변경 사항만 감지하는 가드:
repos:
- repo: https://github.com/raccioly/docguard
rev: v0.46.0
...
- **MCP** (Claude, Cursor, 모든 MCP 클라이언트) — `claude mcp add docguard -- npx -y docguard-cli mcp`; 문서를 확인(guard, score, diagnose 등)하고 한 번에 하나의 경계가 지정된 섹션으로 탐색하는 읽기 전용 도구입니다. 전체 목록은 [docs/ai-integration.md](docs/ai-integration.md)에 있습니다. 레지스트리 매니페스트는 인-레포(`server.json`, Smithery 사용 준비 완료)로 제공됩니다.
- **GitLab CI** — 컴포넌트는 [`templates/ci/gitlab-component.yml`](templates/ci/gitlab-component.yml)에 스테이징됩니다 (SARIF 아티팩트가 포함된 guard/score/ci 작업).
- **Homebrew** — `brew install raccioly/tap/docguard`. 릴리스 워크플로우는 게시된 npm tarball에서 [`packaging/homebrew/`](https://github.com/raccioly/docguard/tree/main/packaging/homebrew)의 포뮬러 템플릿을 렌더링하여 tap에 푸시합니다.
### 핵심 워크플로우
```bash
# 1. Initialize docs for your project
npx docguard-cli init
...
The AI Loop
diagnose → AI reads prompts → AI fixes docs → guard verifies
↑ ↓
└───────────────── issues found? ←──────────────────────┘
diagnose는 주요 명령어입니다. 모든 검증기(validators)를 실행하고, 발견된 모든 실패 지점을 AI가 처리할 수 있는 수정 프롬프트로 매핑하며, 복구 계획(remediation plan)을 출력합니다. 사용자의 AI 에이전트가 이를 실행하여 문서를 수정하고 guard를 실행해 검증합니다.
Mechanical vs. agent fixes
DocGuard는 드리프트(drift)를 두 가지 종류로 나누고, 어느 것이 어떤 유형인지 명확하게 구분합니다:
| Kind | Example | How it's fixed |
|---|
| Mechanical (deterministic) | An endpoint documented in API-REFERENCE.md that the OpenAPI spec confirms is gone | docguard fix --write deletes the row + detail block itself — no AI |
| Agent (needs judgment) | Rewriting an X-Ray prose section as CloudWatch; writing a new endpoint's request/response | Routed to an AI agent via diagnose / fix --doc prompts |
docguard fix --write는 <!-- docguard:generated true -->로 표시된 문서에만 영향을 미치며 (강제로 --force 사용 가능),멱등적(idempotent)이며, 정확히 무엇이 변경되었는지 출력합니다. 산문(Prose) 부분은 에이전트가 처리합니다.
Continuous documentation workflow
guard ──▶ fix --write (mechanical, auto) ──▶ guard ──▶ diagnose (agent prompts for the rest)
- CI / pre-commit:
docguard hooks --type pre-commit --auto-fix는 기계적 수정(mechanical fixes)을 적용하고 문서를 재스테이징(re-stage)한 다음, guard를 실행하는 훅(hook)을 설치합니다. 남아있는 모든 것은 에이전트 프롬프트로 표면화됩니다.
- Agent-driven:
docguard diagnose --auto는 누락된 문서를 스캐폴딩(scaffolds)하고 기계적 수정을 적용한 다음, 나머지 콘텐츠 재작성을 위한 프롬프트를 방출합니다.
- JSON for automation:
guard/diagnose --format json은 mechanicalFixes 배열을 포함하며 모든 이슈를 mechanical과 agent로 태그 지정하므로, 에이전트가 정확하게 적용하거나 위임할 수 있습니다.
☁️ AWS AI-DLC Integration
DocGuard는 AWS AI-DLC 워크스페이스를 자체적으로 읽어 들입니다. 여기에는 더 이상 존재하지 않는 추적 가능성 목표, 완료된 단계에서 남겨진 공백, 단위 작업 후 제거된 산출물, 그리고 사라진 것을 명시하는 에이전트 메모리(AID001–AID004, MEM001–MEM002) 등이 포함됩니다. 또한 DocGuard는 AI-DLC 플러그인 형태로 제공되며, 이의 docguard-guard 센서는 단계가 드리프트(drift)를 도입했을 경우 건설 게이트(construction gate)에서 실패합니다. AI-DLC 가이드를 참조하십시오.
🌱 Spec Kit 통합 (Spec Kit Integration)
DocGuard는 GitHub의 Spec Kit 프레임워크용 커뮤니티 확장 기능입니다. Spec Kit이 /speckit.specify 및 /speckit.plan과 같은 AI 슬래시 명령을 통해 명세(specification)를 생성하는 데 중점을 둔다면, DocGuard는 그 품질을 검증하는 데 중점을 둡니다.
함께 작동하는 방식 (How They Work Together)
┌─────────────────┐ ┌──────────────────┐
│ Spec Kit │ │ DocGuard │
│ │ │ │
...
| 단계 | 도구 | 발생하는 일 |
|---|
| 1. 초기화 (Initialize) | specify init | .specify/ 디렉터리와 템플릿 생성 |
| ... | | |
Spec Kit 프로젝트에서 DocGuard가 검증하는 내용
- spec.md — 필수 섹션(사용자 시나리오, 요구사항, 성공 기준), FR-xxx ID, SC-xxx ID
- plan.md — 요약(Summary), 기술 컨텍스트(Technical Context), 프로젝트 구조 섹션
- tasks.md — 단계별 작업 분해(Phase 1, 2, 3+), T-xxx 작업 ID
- constitution.md —
.specify/memory/constitution.md 또는 프로젝트 루트에서 감지됨
- 요구사항 추적 가능성 (Requirement traceability) — FR, SC, NFR, US, AC, UC, SYS, ARCH, MOD, T ID
Spec Kit 확장 기능으로 설치하기
-green){kind=icon}
