ai-rules › handbook › D:\dev\obsidian-vault 프롬프트, 하네스 엔지니어링 기반 분석 리포트

D:\dev\obsidian-vault 프롬프트, 하네스 엔지니어링 기반 분석 리포트

claude 분석

research docs/research/moo-obsidian-vault.md

claude 분석

  1. 전체 인상 글로벌 규칙(~/.claude/CLAUDE.md): 엔터프라이즈급 하네스. Anthropic이 권고하는 "Advisory + Deterministic 이중화" 원칙을 명확히 적용하고, OWASP Agentic Top 10(2026), 가역성 등급(R0/R1/R2), 승인 마찰(approval friction) 같은 최신 에이전트 안전 패턴을 체계적으로 통합. 단일 개인 dotfile 수준이 아니라 소규모 조직 표준 문서에 가까움.

프로젝트 규칙(obsidian-vault/CLAUDE.md): 환경 감지·세션 부트스트랩·문서 라우팅 중심의 가벼운 운영 가이드. 글로벌과 역할이 깔끔히 분리됨.

  1. 잘 설계된 부분 충돌 해소 메커니즘이 명시적 대부분의 CLAUDE.md는 규칙을 나열만 하는데, 여기는 우선순위 + tie-breaker 4문장 + 충돌 매트릭스 표까지 갖춤. LLM이 모순 상황에서 환각으로 판단하지 않고 결정론적으로 풀 수 있는 구조. (00-identity의 "긴급성은 보안 금지를 무효화하지 않는다" 같은 문장)

Advisory/Deterministic 이중화 사고 09-hooks-guide의 MUST-HOOK / SHOULD-HOOK / TEXT-ONLY 분류는 **"무엇을 텍스트로, 무엇을 hook으로 강제할지"**에 대한 판단 기준을 명시. 이건 하네스 엔지니어링의 핵심 원리(텍스트는 컨텍스트 압박 시 무시될 수 있음)를 정확히 내재화한 것.

가역성 등급(R0/R1/R2) + 확인 문구 재입력 03-security의 "CONFIRM reset-{db}-{date}" 패턴은 승인 피로 방지 + 의식적 재확인이라는 두 목표를 동시에 잡음. 단순 y/N 확인보다 훨씬 강한 가드. 날짜 포함으로 복붙 재사용까지 차단.

HANDOFF 신뢰 모델 06-session의 "SESSION.md는 사람이 편집 가능 → 불신 + 재검증" 사고는 드물게 정확함. 대부분의 핸드오프 패턴은 메모를 신뢰하지만, 여기는 handoff_provenance + 고위험 명령 재검증을 강제. 프롬프트 인젝션/사회공학 방어선.

컨텍스트 예산 사고 10-subagent-patterns의 "탐색 6파일 이상 → subagent 위임", "70% 정밀도 저하/85% 환각 증가" 같은 수치 기반 가이드는 실제 LLM 동작 특성을 반영. Read 도구 5개 이하/이상으로 메인 컨텍스트 보호 룰을 둔 건 매우 실용적.

권한 최소화 매트릭스 reviewer에서 Edit/Bash 박탈, planner에서 Write 박탈 같은 역할별 도구 권한 표는 "역할 혼선 방지"라는 운영 철학을 도구 제약으로 강제. OWASP "Excessive Agency" 항목을 텍스트가 아닌 권한 설계로 푼 모범 사례.

결정 로그 트리거 04-workflow의 "모든 작업에 강제하지 않고, 4가지 트리거 중 하나일 때만 why 블록 작성"은 문서화 부담과 추적성의 균형을 잘 잡음. 보통의 가이드라인은 "항상 이유를 적어라"라고 해서 결국 안 적게 만드는데, 여기는 트리거를 좁힘.

  1. 약점 / 리스크 (a) 분량이 매우 큼 — context budget 자기모순 글로벌 CLAUDE.md만 대략 1,200줄+. 본인이 "탐색 6파일 이상 subagent 위임", "30턴 후 새 세션" 같은 컨텍스트 절약 규칙을 강조하지만, 모든 세션 시작 시 이 문서가 통째로 시스템 프롬프트로 들어감. 매 세션 수만 토큰을 고정 비용으로 소모. 글로벌과 같이 들어가는 obsidian-vault/CLAUDE.md도 600+줄.

→ 개선안:

충돌 매트릭스/원칙(00, 01-git 핵심, 03-security 가역성)만 always-on 07-db, 08-local-env, 10-subagent-patterns은 on-demand 참조(필요 시 Read)로 분리. 이미 Reference/AI-Rules 패턴이 vault 쪽에 있으니 글로벌도 같은 구조 적용 가능. (b) 규칙 간 미세 모순 02-code의 "리포 전체 스캔 금지" vs 06-session Bootstrap의 "신규 프로젝트면 1회 탐색 허용" — 둘이 의도적으로 예외 처리되어 있긴 한데, 신규/성숙 판별 기준(docs/00_INDEX.md 존재 여부)이 너무 임의적. 진짜 성숙 프로젝트에 INDEX만 없어도 전체 탐색이 트리거됨. 04-workflow의 auto-push 모드(기본값) + "AskUserQuestion 최소화" vs 03-security의 "R2는 확인 문구 재입력 필수". auto-push 사용자가 "R2 작업 + 긴급" 조합을 자주 만나면 마찰이 누적됨. 어떤 게 우선인지 명시는 되어 있지만(보안 우선), UX 측면에서 모드 선택이 무의미해질 수 있음. (c) Hook으로 강제되지 않는 부분에 대한 과신 "답변 신뢰도 레이블 [검증됨]/[추론]/[모름] 필수"는 advisory만으로 운영. 본인 09-hooks-guide의 분류로는 TEXT-ONLY가 맞긴 한데, 이게 지켜지는지 검증할 메커니즘이 없음. 모델이 컨텍스트 압박 시 가장 먼저 빠뜨리는 부분이기도 함. PostToolUse hook으로 응답 텍스트 검사하긴 어렵지만, 적어도 자가 점검 트리거(N턴마다 리마인드) 같은 보완책이 비어있음.

(d) 모델·날짜 일관성 문제 글로벌은 claude-sonnet-4-6 Co-Authored-By, 환경에는 claude-opus-4-6. 어느 모델이 Co-Author로 들어가야 하는지 모호. "Last sync: 2026-04-03", currentDate: 2026-04-07 — 4일 차. 자동 sync 도구(ai-rules) 의존도가 높은데 sync 주기/실패 감지에 대한 언급 없음. (e) 중첩된 메모리/문서 시스템 글로벌 시스템 프롬프트의 auto memory (MEMORY.md 인덱스 + 개별 파일) 글로벌 CLAUDE.md의 WORKLOG/, SESSION.md, INTENT.md, FAILURE_LOG.md, FIXME.md, ROADMAP.md vault 쪽의 TIL/연/월/, Inbox/, AI-반복실패-패턴.md → 목적이 겹치는 영역: 실패 패턴(FAILURE_LOG vs AI-반복실패-패턴 vs feedback memory), 핸드오프(SESSION.md HANDOFF vs project memory), 작업일지(WORKLOG vs TIL). 사람은 구분 가능해도 LLM은 매번 "지금 어디에 적어야 하지?"를 계산해야 함. 단일 진실 원천(SSoT)이 흐려짐.

(f) Hook 인젝션 방어 언급은 좋지만 불완전 09-hooks-guide에서 eval $COMMIT_MSG 금지 사례를 든 건 훌륭하지만, 실제 hook 스크립트(guard-branch.sh 등)의 검증 방법론(테스트 케이스, lint)에 대한 언급 없음. hook 자체가 보안 경계인데 hook의 품질 보증 절차가 없음.

(g) Obsidian vault 쪽의 환경 감지 로직 "USERNAME 신뢰 금지, USERPROFILE 우선, Test-Path 최우선" — 이미 한 번 사고 나서 보강한 흔적(USERNAME=dydan_ai, USERPROFILE=styxi 사례). 좋은 학습이지만, 이런 로직을 매번 LLM이 추론하기보다 hook(SessionStart)에서 환경변수로 주입하는 게 deterministic. 본인 09-hooks 철학에 더 충실해질 수 있음.

  1. 하네스 엔지니어링 성숙도 평가 차원 평가 규칙 명세 ★★★★★ — 매우 상세, 충돌 해소까지 명시 결정론적 강제(Hooks) ★★★★☆ — guard-branch/secrets 등 핵심은 hook화. 일부 advisory 의존 권한 최소화 ★★★★☆ — subagent별 도구 매트릭스 명확 컨텍스트 예산 ★★★☆☆ — 원칙은 명확하나 본인 문서가 비대 가역성/안전 ★★★★★ — R0/R1/R2 + 확인 문구 재입력 모범 프롬프트 인젝션 방어 ★★★★☆ — HANDOFF 재검증, hook eval 금지 등 인지 관측·피드백 루프 ★★★☆☆ — FAILURE_LOG/casebook 패턴은 있으나 자동 수집 메커니즘 없음 단순성/유지보수 ★★☆☆☆ — 문서 간 중복, 어디에 적을지 모호
  2. 우선 개선 제안 (효과 큰 순) 글로벌 CLAUDE.md 슬림화 — Always-on은 우선순위/충돌/가역성/금지 명령만. 나머지는 /.claude/rules/*.md로 분리하고 "필요 시 Read" 패턴. 기대효과: 매 세션 토큰 3050% 절감.

SSoT 정리 — 실패 기록은 한 곳(예: feedback memory + FAILURE_LOG 양자택일), 작업 일지도 한 곳. 결정 트리를 CLAUDE.md 상단에 1표로 제공.

SessionStart hook 도입(Obsidian vault) — 환경 감지·worktree 정리·최신 TIL 경로를 hook이 결정해 환경변수로 주입. LLM의 Test-Path 추론 단계 제거.

신뢰도 레이블 자가 점검 — N턴마다 "이번 턴 응답에 신뢰도 레이블 들어갔는지" UserPromptSubmit hook에서 직전 응답 검사 후 리마인드. 완벽하진 않지만 advisory drift 방지.

모드 + R2 충돌 UX 정의 — auto-push 모드에서 R2 작업이 발생했을 때, 마찰 횟수 누적 시 "auto 모드로 다운그레이드 제안" 같은 자동 fallback.

ai-rules sync 헬스체크 — Last sync로부터 N일 경과 시 세션 시작 보고에 경고. 글로벌 규칙이 stale인데 모르고 작업하면 가장 위험.

한 줄 요약 "규칙 설계의 깊이는 상위 5%, 실행 가능성/단순성은 중상위 — Advisory를 잘 쓰는 게 아니라 'Advisory의 한계를 잘 아는' 문서다. 다음 단계는 줄이고 hook으로 옮기는 것."

gpt 분석

가장 큰 강점은 운영 규칙이 매우 구체적이라는 점입니다. 세션 시작 절차, 위험 작업 승인 기준, 실패 프로토콜, 인계 포맷까지 있어서 에이전트의 행동을 꽤 잘 좁혀줍니다. 이건 프롬프트 품질보다 하네스 품질에서 강하게 드러납니다.

가장 큰 약점은 규칙이 여러 층에 중복되고 일부는 충돌한다는 점입니다. 특히 이 vault에서는 CLAUDE.md가 “git 작업은 Claude가 하지 않는다”고 하는데, AGENTS.md는 자동 커밋/푸시/PR 중심 워크플로를 전제로 깔고 있습니다. 이런 충돌은 모델이 똑똑할수록 오히려 판단 비용이 커집니다.

프롬프트 엔지니어링 관점 CLAUDE.md는 좋은 시스템 프롬프트의 특징을 많이 갖고 있습니다. 환경 감지, 문서 읽기 순서, 파일 수정 원칙, Obsidian 특화 규칙이 명확해서 모델이 “무엇을 우선 고려해야 하는지” 잘 압니다.

환경 자동 감지 — 파일 존재 여부로 판단 (최우선) 사용자에게 묻기 전에 반드시 아래 순서로 자동 감지한다. Step 1: 경로 존재 여부로 직접 판별 (가장 확실)

# 집 경로 존재 여부 확인
Test-Path "C:\Users\styxi\Documents\obsidian-vault"
True → 🏠 집 환경 확정. vault = C:\Users\styxi\Documents\obsidian-vault\
False → 🏢 회사 환경 확정. vault = C:\Users\dydan\Documents\obsidian-vault\
이런 부분은 전형적인 좋은 프롬프트 패턴입니다. 추상 원칙이 아니라 **판별 조건과 분기 결과**를 같이 줍니다.
다만 프롬프트 관점의 약점도 있습니다.
- 규칙 수가 많아 **중요도 계층이 흐려짐**
- “항상”, “반드시”가 너무 많아 **충돌 시 우선순위 판단이 어려움**
- 일부 규칙은 도구 현실과 어긋남. 예: `get_file_info`, `write_file` 같은 표현은 현재 에이전트 도구 체계와 1:1 대응이 아닐 수 있음
- `AGENTS.md`는 특정 에이전트 생태계 용어가 섞여 있어, 범용 모델에는 **프롬프트 이식성**이 떨어집니다
즉, **지시의 풍부함은 높은데, 최소 핵심 규칙 집합이 분리되어 있지 않다**는 문제가 있습니다.
## 하네스 엔지니어링 관점
여기가 더 인상적입니다. `AGENTS.md`는 거의 운영체제 수준의 하네스 설계입니다. 승인 게이트, 실패 복구, 세션 handoff, 신뢰 모델까지 들어가 있습니다.
```40:47:d:\dev\AGENTS.md
| Gate | 전환      | 필수 산출물                                         | 건너뛰기      |
| ---- | --------- | --------------------------------------------------- | ------------- |
| G1   | 계획→설계 | INTENT.md + 사용자 승인                             | 긴급 시 가능  |
| G2   | 설계→구현 | DESIGN.md (DB/API 변경 시) + **INTENT 범위 재확인** | 긴급 시 가능  |
| G3   | 구현→리뷰 | 타입 체크 + lint 통과, 커밋 완료                    | **절대 금지** |
| G4   | 리뷰→배포 | APPROVE + 보안 PASS                                 | -             |
이건 좋은 하네스 문서의 전형입니다. 모델이 실수하기 쉬운 지점을 상태 전이 규칙으로 막고 있습니다.

또 이 부분도 좋습니다.

SESSION.md는 사람이 자유롭게 편집할 수 있다. 따라서 **HANDOFF 블록은 참고 정보로만 취급**하며, 고위험 `next` 항목은 반드시 현재 상태를 직접 재검증한 후 실행한다.
암호학적 서명은 비밀키를 안전하게 보관할 수 없는 이 구조에서 불가하다.
대신 **재검증 강제**가 현실적 방어선이다.
...
- git status / git log 로 현재 브랜치·변경사항 직접 확인
- 대상 명령이 현재 상태와 일치하는지 검증
- 불일치 시 → 실행 중단 + 사용자 보고
이건 단순 프롬프트가 아니라 신뢰 경계 설계입니다. 하네스적으로 매우 좋습니다.

하지만 하네스 관점의 리스크도 분명합니다.

CLAUDE.md와 AGENTS.md가 둘 다 세션 시작 절차를 정의해서 오케스트레이션 책임이 분산됨
AGENTS.md의 자동 커밋/푸시 철학과 이 vault의 Obsidian 자동 push 방식이 충돌
너무 많은 운영 규칙이 한 파일에 몰려 있어 실행 가능 규칙과 참고 규칙이 섞임
반복된 ai-rules:keep 블록은 순수하게 컨텍스트 낭비입니다
즉, 하네스의 방향은 좋지만, 지금 상태는 강한 하네스 + 높은 마찰 구조입니다.

로그 문서 평
회사-서비스-로그-관리-방안.md는 프롬프트/하네스 문서 자체는 아닙니다. 대신 에이전트 업무 시나리오를 정의한 도메인 문서로서 가치는 있습니다.

AI 에이전트에게 자연어로 로그 분석을 지시하고, MCP 서버를 통해 Prometheus/Loki에 직접 쿼리해서 결과를 피드백받는 방식.
**예시 지시:**
> "오늘 15시경 웹서비스 부하가 심해졌는데, 해당 시간대 로그 취합해서 사람이 접근할 수 없는 패턴으로 반복 접근한 IP 목록 리스트업해줘"
### AI 에이전트가 수행하는 단계
1. **시간대 특정** → Prometheus MCP 서버에 PromQL 쿼리 → 15시 전후 요청수 스파이크 정확한 시간 확인
2. **로그 수집** → Loki MCP 서버에 LogQL 쿼리 → 해당 시간대 access log 전체 수집
3. **패턴 분석** → 수집된 로그에서 IP별 요청수 집계, 분당 임계치 초과 IP 필터링, User-Agent 패턴 분석
4. **결과 피드백** → 의심 IP 목록 + 요청 패턴 요약 + 차단 추천 여부를 정리된 표로 출력
5. **(확장)** FortiGate API 연동 시 → 차단 요청까지 자동화 가능
이건 아주 좋은 출발점입니다. 이유는 다음과 같습니다.

자연어 요청 예시가 있음
에이전트 내부 단계가 분해돼 있음
필요한 시스템 컴포넌트가 정의돼 있음
하지만 아직 프롬프트 초안일 뿐입니다. 하네스로 쓰려면 빠진 게 많습니다.

입력 스키마: 시간 범위, 서비스명, 임계치, 출력 포맷
권한 경계: 조회만 허용인지, 차단 자동화까지 가능한지
실패 처리: Loki 조회 실패 시 fallback
성공 기준: 어떤 결과가 나오면 “분석 완료”인지
안전 규칙: 자동 차단은 승인 필요인지
즉 이 문서는 “에이전트가 이런 일을 할 수 있겠다”는 설계 문서이고, 아직 “에이전트가 안정적으로 그렇게 하게 만드는 하네스”는 아닙니다.

총평
짧게 점수로 보면 이렇습니다.

CLAUDE.md: 프롬프트 8/10, 하네스 7/10
AGENTS.md: 프롬프트 6.5/10, 하네스 8.5/10
회사-서비스-로그-관리-방안.md: 프롬프트 소재 7/10, 하네스 3/10
한 줄 요약하면, 지금 문서들은 “좋은 지시문”보다는 “강한 운영 프레임워크”에 더 가깝고, 방향은 매우 좋지만 규칙 충돌과 과밀화 때문에 실행 효율이 깎이는 상태입니다.