Agent Pragma
문제점: AI 코딩 에이전트는 규칙을 일관성 있게 따르지 않습니다. 대화 도중 규칙을 잊거나, 복잡한 작업 중에 무시하거나, 부분적으로만 적용하는 경우가 발생합니다. 이를 강제할 메커니즘이 없습니다.
해결책: agent-pragma는 규칙을 기계적으로 주입하고 준수 여부를 검증하는 스킬(skills)을 제공합니다. 규칙은 기억되는 것이 아니라, 모든 구현에 자동으로 실행되는 검증기(validators)에 의해 강제됩니다.
Claude Code와 OpenCode 모두에서 작동합니다.
시스템 요구 사항
- Claude Code 또는 OpenCode
- Git
- uv (
/star-chamber용)
- 결정론적 린팅(deterministic linting)을 위한 언어 툴체인: Go (
golangci-lint), TypeScript (biome, tsc), Python (ruff, ty/mypy)
빠른 시작
Claude Code
-
마켓플레이스 추가:
/plugin marketplace add peteski22/agent-pragma
-
플러그인 설치:
/plugin install pragma@agent-pragma
-
자동 업데이트 활성화 (권장):
/plugin
→ Marketplaces 탭 → agent-pragma 선택 → 자동 업데이트 활성화
제3자 마켓플레이스는 기본적으로 자동 업데이트가 비활성화되어 있습니다. 이를 활성화하면 Claude Code 시작 시 새로운 버전을 자동으로 받을 수 있습니다.
-
모든 프로젝트에서 /validate 실행 — 설정이 필요 없고 즉각적인 가치를 얻을 수 있습니다. 예시 (Go 파일 수정 후):
> /validate
# Validation Results
...
선택적으로 `/setup-project`를 실행하여 프로젝트별 규칙을 구성할 수 있습니다 — [프로젝트 규칙 구성](#configure-project-rules-setup-project) 참조.
> **참고:** 스킬은 CLI 자동 완성에서 `/star-chamber (pragma)`로 표시됩니다. 짧은 형태인 `/star-chamber`가 호출하기 가장 쉬운 방법입니다. 완전히 한정된 형식인 `/pragma:star-chamber`도 작동합니다.
### OpenCode
```bash
# 레포지토리 클론
git clone https://github.com/peteski22/agent-pragma.git
cd agent-pragma
...
이것은 스킬들을 심볼릭 링크(symlinks)하고 ~/.config/opencode/ 디렉토리에 에이전트와 커맨드를 생성합니다. 아무 프로젝트에서나 /validate를 실행하면, 내장된 규칙들과 즉시 작동합니다. 프로젝트별 규칙에 대해서는 프로젝트 규칙 구성을 참조하세요.
대신 전역(globally)이 아닌 특정 프로젝트에 설치하려면:
make install AGENT=opencode PROJECT=/path/to/your/project
즉시 작동하는 기능
모든 스킬은 추가적인 설정 없이 설치 후 작동합니다 (/star-chamber는 API 키가 필요합니다 — 환경 변수 참조).
flowchart TD
A["/validate"] --> B["변경 파일 유형 감지"]
B --> C["적용 가능한 검증기(validators) 전송"]
...
/review는 동일한 검증기 전송 규칙을 사용합니다.
검증기 (Validators)
/validate는 변경된 파일 유형을 기반으로 모든 적용 가능한 검증기를 오케스트레이션(orchestrates)합니다:
| 스킬 | 언어 | 확인하는 내용 |
|---|
/security | 전체 | 비밀 정보, 주입(injection), 경로 순회(path traversal), 인증 격차(auth gaps) |
| ... | | |
코드 검토 (Code Review)
| 스킬 | 기능 |
|---|
/review | 현재 변경 사항에 대해 보안, 상태 기계(state-machine), 오류 처리 + 언어별 검증기를 실행합니다. 구성된 경우 프로젝트 규칙을 주입합니다. |
/star-chamber | 다중 LLM 합의 검토 — 첫 실행 시 제공업체 설정을 위한 프롬프트를 요청합니다 (API 키 필요) |
심각도 수준 (Severity Levels)
| 레벨 | 의미 | 발생하는 일 |
|---|
| HARD | 반드시 수정해야 함 | /implement 완료를 차단함 |
| ... | | |
언어별 규칙은 paths: 프런트매터를 사용하여 일치하는 파일에 적용 범위를 지정합니다. backend/app/main.py를 편집할 때, python.md (범위: backend/**/*.py)와 universal.md가 모두 적용됩니다. 프로젝트 루트의 CLAUDE.local.md는 사용자별 보충 규칙으로 자동 로드됩니다.
두 에이전트 모두 동일한 .claude/rules/*.md 파일에서 규칙을 로드합니다. Claude Code는 CLAUDE.md를 통해 → AGENTS.md로, OpenCode는 AGENTS.md를 직접 통해 로드합니다. 이를 통해 프로젝트 규칙에 대한 단일 진실 공급원(single source of truth)이 유지됩니다.
버전 관리 (Version Control)
생성된 .claude/rules/ 파일을 선택적으로 커밋하여 다른 개발자가 /setup-project를 다시 실행할 필요 없이 동일한 규칙을 얻도록 할 수 있습니다.
CLAUDE.local.md는 사용자별, 기기별 규칙용이므로 gitignore 해야 합니다. 이 파일을 수동으로 생성하는 경우, 개인 규칙을 커밋하지 않도록 .gitignore에 포함되어 있는지 확인하십시오.
git worktree에서는 @import (다른 CLAUDE.md 파일을 포함하는 Claude Code 지시어)를 사용하여 CLAUDE.local.md에서 공유 로컬 규칙 파일(shared local rules file)을 참조하고, 작업 트리마다 중복하는 것을 방지하십시오:
@import ../shared-local-rules.md
전체 파이프라인 (/implement)
자동 검증과 함께 구현(implementation)을 원할 때 사용합니다. 이 예시는 프로젝트 규칙 파일을 생성하기 위해 /setup-project가 실행되었다고 가정하며, 파일이 없더라도 검증기(validators)는 내장된 규칙 세트를 사용하여 계속 작동합니다.
> /implement add input validation to the login form
[Phase 0] Injecting rules from:
...
flowchart TD
A["/implement add user authentication"] --> B["Phase 0: Rules injected from project rules"]
B --> C["Phase 1: Plan commit units, settle commit mode"]
...
핵심 원칙: 검증기(Validators)가 권위적이며, 규칙 파일이 아닙니다. 충돌이 발생하면 검증기가 승리합니다.
환경 변수 (Environment Variables)
| 변수 | 필수 여부 | 설명 |
|---|
STAR_CHAMBER_CONFIG | 아니요 | star-chamber 설정의 사용자 지정 경로 (기본값: ~/.config/star-chamber/providers.json) |
| ... | | |
업데이트 (Updating)
Quick Start에서 자동 업데이트를 활성화했다면, Claude Code가 시작될 때 새 버전이 자동으로 가져와지며 세션을 재시작하라는 알림을 받게 됩니다.
수동으로 업데이트하려면 다음 두 단계를 이 순서대로 모두 수행해야 합니다:
-
마켓플레이스 업데이트 (최신 플러그인 메타데이터를 가져옵니다):
/plugin marketplace update agent-pragma
-
플러그인 업데이트 (새 버전을 설치합니다):
현재 버전을 확인하려면 /plugin을 실행하고 Installed 탭에서 확인하세요.
디렉터리 구조
agent-pragma/
├── .claude-plugin/
│ └── marketplace.json # Claude Code 마켓플레이스 카탈로그
...
Claude Code와 OpenCode는 plugins/pragma/skills/의 스킬과 plugins/pragma/claude-md/의 규칙 파일을 공유합니다. OpenCode는 make install AGENT=opencode에 의해 생성된 심볼릭 링크를 통해 스킬에 접근합니다.
레거시 설치 (사용 중단)
Claude Code용 이전의 make install + $CLAUDE_PRAGMA_PATH 방식은 사용이 중단되었습니다. 대신 플러그인 마켓플레이스를 사용하세요. 자동 업데이트가 활성화되면( Quick Start 참조) 자동으로 업데이트를 처리합니다. 마이그레이션하는 경우, 기존 심볼릭 링크와 환경 변수를 제거하세요:
추가 정보
라이선스
Apache 2.0 - 자세한 내용은 LICENSE를 참조하세요.