Handbook
living handbook · 78개 문서 · guide / log / changes를 한곳에서 탐색
ai-rules는 규칙 저장소이자 운영 지식 베이스다. 이 문서는 어떤 내용이 실제 규칙이고, 어떤 내용이 참고용 가이드인지 빠르게 구분하도록 돕는다.
빠르게 읽기
Core Handbook
- 실행 가능 항목 전체 정리 — npm scripts, 슬래시 명령어, MCP, 거버넌스 스크립트
- Harness Engineering
- AI Risk Tiers
- AI Vibe Coding Guide
- Agent Operating Model
- Git Flow Hygiene
- Human Authority Model
- Agent Autonomy Comparison
- Local Port Policy — 프로젝트별 고정 포트 + 런타임 DB 검증의 근거
- Existing Project Integration — 기존 프로젝트에 ai-rules 적용하는 가이드
- Rule Tiers — 규칙 3계층(Universal/Company/Personal) 분류 + 관리
- Onboarding — 초보자 온보딩 가이드
Research
외부 프로젝트 분석 및 비교 연구. 규칙 개선의 근거 문서.
- ECC vs ai-rules 비교 평가
- Claude Code vs ai-rules 비교 (EN)
- Claude Code vs ai-rules 비교 (KO)
- Claude HARNESS 분석
- 규칙 결합도 진단
- Moo Obsidian Vault 분석
- 통합 개선 로드맵
Extended Reading
- AI Log Automation Model
- ChatOps Reference
- AI Log Entry Template
- Must-Know AI Agent Tech
- PORT_REGISTRY 템플릿 — 프로젝트별 포트 중앙 관리
- 개발 체크리스트 (역할별) — 개선 포인트 스캔용 레퍼런스
- RACI 매트릭스 — 역할 책임 분장표
- PR 템플릿 레퍼런스 — PR 템플릿 구조 가이드
- 2025 AI Log
- 2026-03 AI Log
- 2026-04-01 Living Handbook 시작
- 2026-04-03 Git Flow Hygiene
- 2026-04-04 OSS 비교 분석 및 보강 결정
- 2026-04-04 CI 강화 및 규칙 품질 검증 로드맵
- 2026-04-15 DB 포트 고정 정책 + 런타임 DB 검증
처음 오는 사람용
- 온보딩 가이드 — 5분 퀵스타트 + 유형별 분기
- 워크스페이스 생태계 — 전체 지도 (디렉토리, 규칙 체계, 데이터 흐름)
- 규칙 3계층 관리 — Universal / Company / Personal 분류 + 관리
- Harness Engineering — 규칙 + Hook 설계 철학
- AI Risk Tiers — 자동화 수준 결정 기준
문서 구분
Rules
실제로 에이전트 행동에 영향을 주는 짧은 정책 문서다.
- 위치:
core/*.md,extensions/*.md - 성격: must / must not / approval required
- 예: 보호 브랜치 금지, DB 파괴 작업 금지, 세션 handoff 규칙
Guides
규칙의 배경, 설계 철학, 예시, 운영 패턴을 설명하는 문서다.
- 위치:
docs/guide/*.md - 성격: why / examples / patterns / trade-offs
- 예: 하네스 엔지니어링, risk tier, AI 협업 방식
Research
외부 프로젝트 비교 분석, 규칙 결합도 진단, 개선 로드맵 등 의사결정 근거 문서다.
- 위치:
docs/research/*.md - 성격: analysis / comparison / diagnosis / roadmap
- 예: ECC vs ai-rules 비교, 규칙 결합도 진단, 통합 개선 로드맵
Reference
반복해서 찾아보는 템플릿, 체크 포인트, 기술 레퍼런스를 모아둔 문서다.
- 위치:
docs/reference/*.md - 성격: template / reference / field guide
- 예: 로그 템플릿, 필수 AI 기술 레퍼런스
Change Log
시간순으로 바뀐 판단과 구조를 기록하는 문서다.
- 위치:
docs/changes/*.md - 성격: changed / why / impact
- 예: 새 handbook 도입, 승인 마찰 정책 조정, risk tier 개편
Issues
프로젝트에 ai-rules를 sync/적용하면서 발견된 결함, 설치 누락, 설계 충돌을 수집한다.
- 위치:
docs/issues/*.md(인덱스) - 성격: bug / workaround / upstream-fix
- 예: ISS-001 husky v9 hook 반쪽짜리 설치
Log
날짜 기준으로 실제 릴리즈, 사고, 기술 변화를 기록하는 문서다.
- 위치:
docs/log/YYYY/MM/*.md - 성격: what happened / core technology / why it matters / source
- 예: 모델 출시, 제품 기능 발표, 공식 incident, 월간 요약
추천 읽기 순서
- Harness: 왜 규칙만으로는 부족한지 이해
- Risk Tiers: 어떤 작업을 어디까지 자동화할지 이해
- Vibe Coding: AI와 함께 일할 때 좋은 작업 단위 이해
- Log: 실제 월간 변화와 기술 흐름 확인
- 세부 계획/분석 문서: 실제 적용 방안 확인
운영 원칙
- 규칙은 짧게 유지한다.
- 긴 설명과 사례는 handbook으로 분리한다.
- 날짜별 변화는
docs/changes/에 남긴다. - 안정화된 내용만
core/규칙으로 승격한다.
문서 카테고리
Guide
AI 코딩 에이전트 자율성 모델 비교
주요 AI 코딩 에이전트의 자율성 모델을 비교하고, ai-rules 04-workflow 모드 체계의 위치를 파악한다
운영 파라미터 가이드
자율 모드 에스컬레이션의 "예산 초과 신호" 임계값을 관리한다. 규칙 본문(`core/04-lifecycle.md`)에 하드코딩하지 않는 이유와, 환경별 튜닝 방법을 정의한다.
Agent Operating Model
특정 프로젝트가 아니라 여러 저장소에서 공통으로 적용할 수 있는 에이전트 팀 운영 모델을 정의
AGENTS.md Adapter 설계 계획
### 현재 ai-rules agents/ 포맷
AI Log Automation Model
아침/저녁 자동 업데이트용 AI 로그 시스템을 설계할 때 필요한 흐름, 저장 구조, 검증 구조를 짧게 정리
AI Risk Tiers
작업 위험도를 공통 언어로 분류하고, 승인 방식과 실행 권한을 tier별로 일관되게 나누기 위한 기준
AI Rules 시스템 개선 분석 보고서
### 트리거가 된 실제 사건
AI Rules 시스템 개선 체크리스트
### 그대로 반영
AI Rules 시스템 개선 계획안
``` Phase 1 (즉시) — rule 파일 텍스트 수정 (3개 파일) Phase 2 (단기) — 신규 core 파일 추가 (2개 파일) Phase 3 (중기) — 구조 개선 (Hooks 가이드 + Subagent 포맷 전환) Phase 4 (장기
AI Vibe Coding Guide
AI와 함께 코드를 만들 때 생산성은 높이고, 범위 드리프트와 품질 저하는 줄이기 위한 협업 가이드
AITEM 기반 공통 거버넌스 추출
AITEM에서 이미 검증된 AI 개발 운영 방식을 공통 정책으로 추출하고, `ai-rules` 전체에 일반화 가능한 요소와 프로젝트 고유 요소를 구분한다.
우회 정책 관리 기준
`SKIP_E2E`, 수동 승인 우회, 조건부 배포 같은 예외 경로가 무질서하게 퍼지지 않도록, 허용 범위와 감사 기준을 명확히 정의한다.
ChatOps Reference
`openclaw + Telegram` 운영 패턴을 공통 운영 모델에 연결하기 위한 참조 문서
Claude Code Extensions 활용 가이드
| 기능 | MD 파일만? | 추가 필요 | ai-rules 관리 현황 | |------|-----------|---------|-----------------| | **Skills** | ✅ | 없음 | 🟡 일부 (`commands/playwrig
CLAUDE.md Slimming Plan
### 파일별 줄 수 (2026-04-01 기준)
실행 가능 항목 전체 정리
```bash npm run <script> ```
공통 배포 계약
프로젝트별 서버/인프라가 달라도 동일한 배포 정책과 검증 흐름으로 운영할 수 있도록 공통 계약을 정의한다.
도메인별 검증 임계값 모델
프로젝트별 verifier/judge 시스템이 공통 점수 축을 공유하면서도, 도메인 민감도에 따라 추가 임계값을 선택적으로 활성화할 수 있도록 기준 모델을 정의한다.
기존 프로젝트 통합 가이드
| 항목 | 신규 프로젝트 | 기존 팀 프로젝트 | |------|------------|----------------| | `CLAUDE.md` | 새로 생성 | `Last sync:` 마커 없으면 건너뜀 | | `.claude/hooks/*.sh`
Git Flow Hygiene
코드 변경 작업 시작 전후로 수행할 git 위생 절차를 정의하여, 오래된 소스 기반 작업·충돌·병렬 에이전트 간섭을 예방한다
ai-governance → ai-rules 통합 계획
`d:/dev/ai-governance`를 `ai-rules` sync 시스템에 통합하여 모든 프로젝트에 배포 가능하게 만들기
Harness Engineering
`ai-rules`를 "규칙 문서 모음"에서 "정책을 실제로 집행하는 시스템"으로 확장하기 위한 공통 가이드
Human Authority Model
에이전트 환경에서 "사람의 의식적 지시"와 "에이전트 간 텍스트 전달"을 구분하는 권한 확인 체계를 정의한다
왜 "프로젝트별 고정 포트 + 런타임 DB 검증"인가
**앱 포트도 DB 포트도 "프로젝트별 고정 할당"으로 관리하고, 앱 부팅 시 `current_database()`로 연결된 DB 이름을 검증한다.** 자동 포트 탐색(find-port)은 AI 에이전트 환경과 맞지 않아 deprecated.
MCP 통합 가이드
### 목적
ai-rules 온보딩 가이드
| 문서 | 내용 | |------|------| | [workspace-ecosystem.md](../../extensions/workspace-ecosystem.md) | 전체 지도 — 디렉토리 분류, 규칙 체계, 데이터 흐름 | | 이 문서 |
프로젝트별 운영 역량 매트릭스
각 프로젝트가 현재 어느 수준의 AI 운영 구조를 갖추고 있는지 한눈에 관리하고, 공통화 진행 상태와 남은 격차를 명확히 한다.
규칙 테스트 시나리오
각 시나리오: - **상황**: 어떤 맥락인가 - **입력**: 사용자가 뭐라고 했는가 - **올바른 AI 행동**: 규칙대로라면 어떻게 행동해야 하는가 - **잘못된 AI 행동**: 규칙 위반 시 어떻게 행동하는가 - **관련 규칙**: 어떤 rul
규칙 3계층 관리 가이드
| 계층 | 판단 기준 | 예시 | |------|---------|------| | **Universal (범용)** | 바꾸면 안전에 문제가 생기는가? | 시크릿 금지, force-push 금지, R2 차단, OWASP | | **Company (
스킬 사용 가이드
| 스킬 | 호출 | 한줄 설명 | |------|------|----------| | Planning | `/planning` | 작업 계획 수립 (Plan Mode) | | Design Doc | `/design-doc` | 설계 문서 작성 (AD
규칙 승격 체계
규칙을 많이 쓰는 것보다 **검증된 규칙만 유지하는 것**이 더 중요하다.
Sync Operations Guide
``` profiles/{project}.yaml ↓ 블록 조립 (core/ + extensions/) ↓ 어댑터 변환 (claude-code, cursor, plain, governance, tooling) ↓ output/{project}/ ← 중
WORKLOG and Failure Learning
프로젝트 진행 맥락을 `INTENT.md`/`SESSION.md`만으로 놓치지 않도록, 시간순 작업 스냅샷과 실패 학습 문서를 분리해 관리한다.
Reference
개발 체크리스트 (역할별)
### 문제 정의 · 기회 발굴 - [ ] 해결하려는 문제 명확화 (Problem Statement 1~2문장) - [ ] 정량·정성 데이터로 문제 입증 - [ ] 기회 가설 · 검증 방법 정의 - [ ] 경쟁 서비스 · 대체재 분석 - [ ] 비즈니
역할 책임 분장표
| 작업 | 기획 | 디자인 | 아키텍트 | UI/UX | FE | BE | 보안 | QA | |------|:---:|:---:|:---:|:---:|:---:|:---:|:---:|:---:| | PRD · User Story 작성 | **A/R*
PR 템플릿 레퍼런스
```markdown ## 변경 요약
AI Log Entry Template
날짜별 AI 로그 문서를 짧고 검증 가능하게 작성하기 위한 공통 템플릿
[컨셉명]
[디자인1] Theme-to-Design Engine 기획 이전 단계/기획 구조 디자인 엔진 지침 당신은 “MOKA Theme Design Engine”입니다.
[컨셉명]
[디자인2] Visual Design Engine 실제 디자이너가 뽑는 수준의 “컨셉 시안 세트”를 여러 갈래로 생성 당신은 “MOKA Design Engine”입니다.
reference/design-3
[디자인3] Universal Brand Graphic System Domain-Agnostic Visual Identity Generator 🌍 Unified Brand Graphic System GPT v2 (Concept Lock → Q&A →
reference/design-4
UI / UX Prompt Architect 도메인/이미지 분석 디자인 제안
Must-Know AI Agent Tech
handbook를 읽을 때 먼저 알아두면 좋은 핵심 AI agent 기술 개념을 짧고 실무적으로 정리
PORT_REGISTRY 템플릿
여러 프로젝트를 동시에 띄우는 로컬 개발 환경에서 **앱 포트와 DB 포트를 프로젝트별로 영구 고정 할당**하기 위한 중앙 레지스트리.
AI 워크플로우 스킬 전략 & 안정화 설계
**속도로는 Claude와 오픈소스를 이길 수 없다.** 경쟁선을 속도에서 **깊이 · 책임 · 판단 · 검증**으로 이동시킨다.
Changes
worktree + develop 자동 병합
`scripts/sync.mjs --apply` 는 각 target 프로젝트의 working tree 에 규칙 파일을 직접 쓴다. 이 때문에 다음 문제가 있었다.
DB 포트 고정 정책 + 런타임 DB 검증 도입
앱 포트·DB 포트 모두 **프로젝트별 고정 할당(1-B)** 으로 통일하고, 앱 부팅 시 `current_database()`로 연결 DB를 검증하는 정책(E)을 추가했다. 자동 포트 탐색(find-port)은 **deprecated**. 중앙 레지
Git Flow Hygiene + Human Authority Model 가이드 추가
`core/01-git.md`에 금지 명령, 브랜치 규칙, 커밋 규칙은 있지만, 작업 시작 전 소스 현행화, push 전 충돌 사전 확인, 병렬 에이전트 격리 같은 기본 위생 절차가 빠져 있었다. AITEM과 AX-Studio에서는 이미 BRANCH_
Living Handbook 시작
`ai-rules`는 원래 규칙과 동기화 시스템 중심으로 설계되었다. 하지만 실제 운영 과정에서 규칙의 배경, 하네스 설계 철학, 위험도 체계 같은 내용을 노션이 아닌 저장소 안에서 함께 관리할 필요가 커졌다.
2026-04-04 CI 강화 및 규칙 품질 검증 로드맵
gstack/OSS 비교에서 도출된 CI 및 검증 강화 계획
2026-04-04 OSS 비교 분석 및 보강 결정
gstack, 유사 OSS 프로젝트와의 비교 분석 결과 및 ai-rules 보강 방향 결정 기록
Checklist
design
issues
ai-rules 적용 이슈 로그
- **재발 방지**: 한 프로젝트에서 겪은 함정을 다른 프로젝트 sync 시 다시 겪지 않도록 한다. - **ai-rules 개선 근거**: 인덱스의 이슈들이 쌓이면 sync 로직, adapter, hook 템플릿의 어느 부분이 취약한지 드러난다.
작업 명세
`scripts/export_ai_logs.ps1` 원본(ai-rules)에 3가지 버그가 있어 AITEM에서 수정/검증 완료:
ISS-001: husky v9 hook 반쪽짜리 설치로 모든 커밋 경로 차단
- **ID**: ISS-001 - **발생 프로젝트**: AX-Studio-plan (d:\dev\AX-Studio\AX-Studio-plan) - **발생 날짜**: 2026-04-03 (`f5a5fd1` 커밋으로 husky hook 배포) - *
plan
research
Claude Code 공식 거버넌스 vs ai-rules 비교 분석
### 확인 범위
Claude Code 커뮤니티 Hook/거버넌스 프로젝트 비교 분석
### 확인 범위
AI 서비스 운영 전 사전 대응 프레임워크
AITEM 프로젝트의 Tier 2 (머신 판정 시스템) 진입에는 Golden Set 50개+ 수집이 필수 조건이다. Golden Set은 **실제 운영 데이터에서만 나올 수 있는** 자원이므로, 운영 없이는 Tier 2에 진입 불가능한 구조다.
ai-rules 로드맵 Before/After 비교
| 지표 | Before (P1 이전) | After (P19 완료) | 변화 | |------|-----------------|-----------------|------| | CLAUDE.md 줄 수 | 2,500+ | 409 (slim) | **
비교 분석
둘 다 Claude AI를 기반으로 하지만 **실행 환경과 인터페이스**가 다릅니다.
AI 팀원 출근시키기
``` 매일 아침 9시, Telegram으로 이런 메시지가 온다:
anthropics/claude-code
이 문서는 본 저장소가 어떤 "하네스(harness)"로 구성되어 있는지를 5개 축으로 분해하고, 글로벌 CLAUDE.md 규칙(09-hooks-guide, 10-subagent-patterns)과의 갭을 정리한다.
Comparative Analysis
### What We Examined
비교 분석 (After — P19 완료)
이전 분석(§0)과 동일한 한계가 적용된다: - Claude Code = **플랫폼 기능** (런타임 보장), ai-rules = **운영 프로세스/정책** (Advisory + Hook 이중화) - Anthropic 비공개 기능은 반영하지 않았으며,
비교 분석
### 확인 범위
P19 완료)
- GitHub: 140K+ Stars, 170+ contributors - npm 배포 (`ecc-universal`), selective install 지원 - 구성: 39개 에이전트, 181개 스킬, 79개 커맨드, 포괄적 hook 시스템
ECC vs ai-rules 하네스 평가 비교
- GitHub: 140K+ Stars, 170+ contributors - npm 배포 (`ecc-universal`), selective install 지원 - 버전: v1.10.0 (2026-04-05 기준) - 구성: 39개 에이전트, 181개
비교 분석
| 항목 | GSD | ai-rules | |------|-----|----------| | 핵심 문제 | Context rot — 작업 진행 중 컨텍스트 품질 저하 | 규칙 강제 — 에이전트가 안전하게 작동하도록 정책 계층 제공 | | 접근 | **
비교 분석
| 항목 | Hermes Agent | ai-rules | |------|-------------|----------| | 핵심 문제 | **자기 개선하는 범용 AI 에이전트** — 플랫폼·모델·인프라 불문 | **규칙 강제** — 에이전트가 안전하게
Research 종합 분석
| 문서 | 비교 대상 | 핵심 관점 | |------|----------|----------| | [claude-code-vs-ai-rules](claude-code-vs-ai-rules.md) | Claude Code 공식 플랫폼 | 플랫폼 vs
D:\dev\obsidian-vault 프롬프트, 하네스 엔지니어링 기반 분석 리포트
claude 분석
Rule Coupling Diagnosis
| Rule | Lines | Role | |---|---:|---| | 00-identity | 78 | Meta (priority + conflict matrix) | | 01-git | 113 | Guardrail | | 02-code | 65
Superpowers vs ai-rules 비교 분석
| 차원 | **Superpowers** | **ai-rules** | |------|----------------|-------------| | 핵심 목표 | AI 에이전트의 **행동 패턴 교정** (워크플로우 강제) | AI 에이전트의 **규칙 배
P19 완료)
| 차원 | **Superpowers** | **ai-rules (After)** | |------|----------------|---------------------| | 핵심 목표 | AI 에이전트의 **행동 패턴 교정** (워크플로우 강제) |