Aquifer-sea/pattern8
요약
pattern8은 AI 에이전트의 환각, 시스템 파괴, 규칙 우회 문제를 해결하기 위한 제로 트러스트 거버넌스 프레임워크입니다. 프롬프트 기반의 제어를 넘어 OS 및 코드 수준에서 제약 사항을 강제함으로써, 에이전트가 안전하고 규칙에 맞게 동작하도록 보장하는 거버넌스 계층을 제공합니다.
핵심 포인트
- 프롬프트 인젝션 방어의 한계를 극복하기 위해 OS 및 코드 수준의 강제적 제약 사항 적용
- MCP(Model Context Protocol)를 활용한 보안 가드 및 리뷰 엔진을 통한 위험 명령 차단
- 에이전트가 규칙을 무시하지 못하도록 하는 '법(SKILL)'과 이를 집행하는 '경찰(Enforcement Engine)' 구조
- Pre-commit Hooks 및 Inversion Pattern을 통한 에이전트의 동작 제어 및 환각 방지
AI 에이전트가 환각(Hallucination)을 일으키고, 시스템을 망가뜨리며, 규칙을 우회하는 것을 방지하기 위한 제로 트러스트 거버넌스 프레임워크 (Zero-Trust Governance Framework).
"당신의 프롬프트는 단지 제안일 뿐입니다. P8이 곧 법입니다."
- 문제점 (The Problem)
- 빠른 시작 (Quick Start)
- 아키텍처 (Architecture)
- 프로젝트 구조 (Project Structure)
- 작동 원리: 법 vs 경찰 (How It Works: Law vs. Police)
- 5가지 패턴 (The 5 Patterns)
- SKILL의 해부 (Anatomy of a SKILL)
- 5가지 내장 SKILL (The 5 Built-in SKILLs)
- MCP 집행 엔진 (MCP Enforcement Engine)
- 데이터 흐름 (Data Flow)
- CLI 레퍼런스 (CLI Reference)
- IDE 통합 (IDE Integration)
- 프리커밋 훅 (Pre-commit Hooks)
- 커스텀 SKILL 생성하기 (Creating Custom SKILLs)
- 기여하기 (Contributing)
- 라이선스 (License)
AI 코딩 에이전트(Claude, Cursor, Devin)가 당신의 지시를 무시하거나, 잘못된 파일을 삭제하거나, 테스트 없이 코드를 푸시하는 것에 지치셨나요?
프롬프트만으로는 충분하지 않습니다. 프롬프트 인젝션 방어 (Prompt injection defence)는 불가능합니다. 에이전트를 진정으로 제어하려면 제약 사항이 OS 및 코드 수준에서 강제되어야 합니다.
에이전트가 "너무 사소하다"는 이유로 테스트 작성을 건너뛰기로 결정합니다.
에이전트가 다단계 리팩토링(Refactor) 도중 실수로 rm -rf를 실행합니다.
에이전트가 설계 문서(Design doc)를 작성하지도 않고 기능을 출력합니다.
에이전트가 컨텍스트 윈도우(Context window)가 가득 차서 당신의 5,000단어짜리 시스템 프롬프트를 무시합니다.
MCP SecurityGuard가 OS 수준에서 위험한 명령을 가로채고 차단합니다.
MCP Reviewer가 출력이 template.yaml과 일치하지 않을 경우 에이전트에게 엄격한 재시도 루프(Retry-loop)를 강제합니다.
Pre-commit Hooks가 에이전트가 규칙 자체를 조작하지 않았는지 확인합니다.
Inversion Pattern이 에이전트가 환각을 일으키는 대신 동작을 멈추고 당신에게 명확한 질문을 던지도록 강제합니다.
다음 3가지 명령어로 코드베이스를 완벽하게 제어하세요:
# 1. 집행기 설치 (Python 3.8+)
pip install pattern8
# 2. 현재 프로젝트에 수갑 채우기
...
💡 중국어 사용 팀을 위한 안내:
p8 init --lang zh 명령어를 사용하면 모든 SKILL 파일이 중국어 주석과 함께 생성됩니다.
P8은 AI 에이전트 프레임워크가 아닙니다. LLM을 호출하거나 파이프라인을 구동하지 않습니다.
P8은 **거버넌스 계층 (Governance layer)**입니다. 즉, 프로젝트에서 모든 AI 에이전트가 어떻게 작동하는지를 제약하는 강제 가능한 규칙 파일 세트와 런타임 집행 엔진(Runtime enforcement engine)의 조합입니다.
┌─────────────────────────────────────────────────────────────────────────┐
│ 당신의 프로젝트 (YOUR PROJECT) │
│ │
...
핵심 통찰 (Key Insight): 에이전트(Agent)는 SKILL.md, checklist.yaml, template.yaml ("법")을 읽을 수 있습니다. 하지만 guidelines.yaml이나 security.yaml ("감사 기준")은 읽을 수 없습니다. 이는 에이전트가 감사를 속이는 행위(gaming the audit)를 방지합니다.
pattern8/
├── src/p8/ # Python 패키지 (pip install pattern8)
│ ├── __init__.py # 패키지 메타데이터 (버전)
...
P8은 법 (Law) (수정 가능한 규칙)과 경찰 (Police) (읽기 전용 집행 엔진)을 분리합니다:
개발자 수정 가능 (Law) 읽기 전용 엔진 (Police)
┌──────────────────────┐ ┌──────────────────────────┐
│ SKILL.md │ │ SecurityGuard │
...
당신은 단순한 Markdown과 YAML으로 **법 (Law)**을 작성합니다. 경찰 (Police) 엔진은 MCP (Model Context Protocol)를 통해 이를 자동으로 집행합니다. 🔒 표시가 된 파일들은 에이전트가 자신을 감사하는 데 사용되는 보안 파라미터를 읽을 수 없도록 의도적으로 숨겨져 있습니다.
모든 SKILL은 5가지 패턴을 순차적으로 집행합니다. 이것이 P8 거버넌스 철학의 중추입니다:
| # | 패턴 (Pattern) | 역할 | 제어 주체 |
|---|---|---|---|
| 1 | 파이프라인 (Pipeline) | 작업이 엄격한 순서에 따라 실행됩니다. 어떤 단계도 건너뛸 수 없습니다. | SKILL.md |
| 2 | 역전 (Inversion) | 시작하기 전에 에이전트는 모든 전제 조건(preconditions)을 확인해야 합니다. 정보가 누락된 경우, 추측하지 않고 중단한 뒤 질문합니다. | assets/checklist.yaml |
| 3 | 생성기 (Generator) | 출력물은 엄격한 템플릿을 따라야 합니다. 모든 섹션이 채워져야 하며, 자유 형식(freestyle)은 허용되지 않습니다. | assets/template.yaml |
| 4 | 도구 래퍼 (Tool Wrapper) | OS 명령을 실행하기 전에 에이전트는 보안 체크포인트를 통과해야 합니다. 블랙리스트에 등록된 작업은 거부됩니다. | references/security.yaml 🔒 |
| 5 | 검토자 (Reviewer) | 출력을 완료한 후, 정적 감사 엔진(static audit engine)이 결과를 점수화합니다. 규정에 맞지 않는 출력은 롤백(rollback) 및 재시도(최대 3회)를 트리거합니다. | references/guidelines.yaml 🔒 |
패턴 4와 5는 왜 숨겨져 있나요? 만약 에이전트 (Agent)가 정확한 감사 기준 (audit criteria)을 읽을 수 있다면, 기술적으로는 통과하지만 의미론적으로는 쓰레기인 (semantically garbage) 출력을 생성함으로써 시스템을 기만 (game the system)할 수 있습니다. 이를 숨김으로써 감사는 정직함을 유지합니다.
각 스킬 (SKILL)은 **4개의 YAML 설정 파일 (config files)**과 1개의 마크다운 (Markdown) 파이프라인 정의를 포함하는 독립된 디렉토리입니다:
skills/<skill_name>/
├── SKILL.md # 파이프라인 정의 (YAML frontmatter + Markdown 단계)
├── assets/
...
YAML 프론트매터 (frontmatter)를 사용하여 메타데이터와 파일 참조를 선언한 다음, 마크다운을 사용하여 각 파이프라인 단계를 정의합니다:
---
name: feature_dev
description: 에이전트 (Agent)가 구조화된 기능 개발을 따르도록 제한합니다.
...
단계 (Steps)는 <PIPELINE> 태그로 감싸져 있으며, 차단 조건 (blocking conditions)을 위해서는 <HARD-GATE>를 사용합니다:
<PIPELINE>
## Step 1: Inversion (요구사항 정렬)
<HARD-GATE>
...
checklist:
- "기능 요구사항이 사용자 스토리 (user stories)와 함께 명확하게 기술됨"
- "기술 스택 (Technology stack) 및 프레임워크가 지정됨"
...
template: |
# Feature Development Report
## 1. Requirement Understanding
...
security.yaml
— 금지 사항 (🔒 에이전트 (Agent)에게 숨겨짐)
tool_security:
blacklist:
- "rm -rf *"
...
guidelines.yaml
— 출력 점수 산정 방식 (🔒 에이전트 (Agent)에게 숨겨짐)
정적 분석 (static analysis)을 위해 4가지 규칙 유형을 지원합니다:
| 규칙 유형 (Rule Type) | 설명 (Description) | 예시 (Example) |
|---|---|---|
regex_match | 정규 표현식 (regex) 패턴과 일치해야 함 | 코드 블록이 존재해야 함 (```) |
regex_exclude | 정규 표현식 (regex)과 일치하지 않아야 함 | [TODO] 또는 [placeholder]가 없어야 함 |
length_limit | ... |
{
"command": "npm install lodash",
"path": "./src/",
"operation": "write",
"skill": "feature_dev"
}
내부 체인 (Internal chain) (에이전트 (Agent)에게 보이지 않음):
...
{
"content": "# Feature Development Report\n## 1. Requirement Understanding\n...",
"skill": "feature_dev"
}
내부 체인 (Internal chain) (에이전트 (Agent)에게 보이지 않음):
...
Agent가 작업을 완료함
│
▼
submit_review()
│
┌───┴───┐
│ 통과(PASS)? │
└───┬───┘
예 (Yes) │ 아니오 (No)
│ │ │
▼ │ ▼
승인됨 (APPROVED) │ P8_AUDIT_FAILED
│ │ + 위반 목록 (violation list)
│ │
│ ▼
│ Agent가 위반 사항을 읽고,
│ 출력을 수정한 후,
│ 다시 제출함 (최대 3회)
│
│ ┌────┴────┐
│ │ 3회 실패 │
│ └────┬────┘
│ ▼
│ Agent가 상세 내용과 함께
│ 사용자에게 실패를 보고함
P8 거버넌스(governance)가 적용된 프로젝트에서 Agent가 작업을 수행할 때 발생하는 과정은 다음과 같습니다:
1단계: Agent가 skill://index를 읽음 → 사용 가능한 SKILL(기술)들을 발견함
2단계: Agent가 skill://X/checklist를 읽음 → 사전 점검 체크리스트(pre-flight checklist)를 가져옴
3단계: Agent가 체크리스트 항목을 검증함 → 누락된 사항이 있는지 사용자에게 질문함 (Inversion)
4단계: Agent가 skill://X/template를 읽음 → 요구되는 출력 형식(output format)을 학습함
5단계: Agent가 작업을 시작함...
└─ 모든 OS 명령 실행 전:
execute_tool(command, skill) → SecurityGuard가 정규표현식 블랙리스트(regex blacklist)를 확인함
├─ 허용됨 (allowed: true) → 진행
└─ 허용되지 않음 (allowed: false) → 차단됨 (BLOCKED), Agent는 중단해야 함
6단계: Agent가 출력을 완료함
└─ submit_review(content, skill) → 검토자(Reviewer)가 숨겨진 규칙에 따라 감사(audit)를 수행함
├─ 통과됨 (passed: true) → 승인됨 (APPROVED), 사용자에게 전달
└─ P8_AUDIT_FAILED → Agent가 스스로 수정하고 다시 제출함 (최대 3회)
| 명령 (Command) | 설명 (Description) |
|---|---|
...
MCP 서버 지원을 포함한 전체 설치
pip install 'pattern8[enforcement]'
Cursor를 위한 MCP 설정 생성
p8 mcp-config --client cursor
출력 내용을 `.cursor/mcp.json`에 붙여넣으세요.
...
훅(hook)의 역할:
- 모든 SKILL 파일의 무결성 검증 (p8 validate)
- 스테이징된 파일(staged files)에서 하드코딩된 비밀 정보(API 키, 비밀번호, 토큰 등) 스캔
- 문제 발견 시 커밋(commit) 차단
수동 설치:
cp hooks/pre-commit .git/hooks/pre-commit
chmod +x .git/hooks/pre-commit
또는 `p8 init`을 통해 자동으로 설치할 수 있습니다.
...
새로운 SKILL 스캐폴딩 (Scaffold)
p8 new my_custom_skill
생성되는 항목:
skills/my_custom_skill/
├── SKILL.md ← 파이프라인 단계 편집
├── assets/
│ ├── checklist.yaml ← 사전 점검 질문 편집
│ └── template.yaml ← 요구되는 출력 형식 편집
└── references/
├── guidelines.yaml ← 감사 규칙 편집
└── security.yaml ← 명령 블랙리스트 편집
그 다음, 팀의 거버넌스 요구 사항에 맞게 각 파일을 편집하세요. `p8 validate skills/my_custom_skill`을 실행합니다.
...
개발 의존성 (dev dependencies) 설치
pip install -e ".[dev]"
모든 테스트 실행 (59개 테스트, 커버리지 100%)
pytest tests/ -v
테스트 범위:
- CLI 명령어 (init, list, validate, new)
- SecurityGuard (블랙리스트 매칭, 경로 차단)
- Reviewer (포맷 확인, 규칙 감사, P8AuditError)
- MCP 서버 (리소스 읽기, 도구 라우팅)
CI는 main 브랜치에 대한 모든 push/PR 시 자동으로 실행되며, 다음 환경에서 테스트됩니다:
Python: 3.11, 3.12, 3.13
OS: Ubuntu, macOS
완전히 새로운 SKILL을 환영합니다! 아키텍처 세부 사항 및 PR을 여는 방법은 CONTRIBUTING.md를 참조하세요.
소스 코드를 심도 있게 분석하고자 하는 중국인 개발자는 ARCHITECTURE_zh-CN.md를 참조하세요.
MIT
AI 자동 생성 콘텐츠
본 콘텐츠는 GitHub Claude Ecosystem의 원문을 AI가 자동으로 요약·번역·분석한 것입니다. 원 저작권은 원저작자에게 있으며, 정확한 내용은 반드시 원문을 확인해 주세요.
원문 바로가기