Philosophy & Direction

한눈에 보기

KeystoneHub의 출발점은 “AI와 함께 일하는 방식을 어떻게 시스템으로 만들 것인가”입니다. 이 문서는 전체 문서의 철학적 입구로, 실패를 규칙으로 바꾸고 규칙을 자동화로 승격하는 운영 원리를 먼저 설명합니다.

• 핵심 질문: 같은 실수를 반복하지 않기 위해 무엇을 기록하고 무엇을 자동화할 것인가?
• 읽는 대상: KeystoneHub를 처음 보는 사람, AI 운영 철학을 빠르게 이해하려는 사람
• 연결 문서: Operating Model, System Architecture, Retrospective Loop

이 문서에서 확인할 것

• 실패 → 규칙 → 자동화로 이어지는 기본 루프
• Code-as-Spec과 가역성 기반 의사결정 원칙
• AI agent를 단순 도구가 아니라 역할을 가진 팀원으로 운영하는 방향

핵심 철학

실패 → 규칙 → 자동화

이 시스템의 근본 원리는 단순합니다: 같은 실수를 두 번 하지 않는다.

1. 개발 중 실수가 발생하면 fix: 커밋으로 기록된다
2. 세션 종료 시 hook이 이 커밋을 감지하고 분석 요청을 생성한다
3. 다음 세션에서 /self-improve가 실패 패턴을 규칙(rule)으로 결정화한다
4. 규칙이 2회 이상 위반되면 SOFT(경고) → HARD(차단) hook으로 자동 승격된다

이것이 Loopy-Era — Karpathy가 말한 “AI가 스스로 개선하는 시대”의 실제 구현입니다.

flowchart TD
  A["실패 또는 반복 실수"]
  B["기록<br/>fix commit / evidence"]
  C["분석<br/>session end / self-improve"]
  D["규칙화<br/>rule / checklist"]
  E["자동화<br/>hook / eval / doctor"]
  F["다음 작업에서 차단 또는 안내"]

  A --> B --> C --> D --> E --> F
  F -.-> A

Code-as-Spec

기획 문서, Figma, 와이어프레임은 입력이지 스펙이 아닙니다. 최종 스펙은 항상 코드(타입/상수/컴포넌트)와 CLAUDE.md(규칙/자산 등록)에 존재합니다. 어떤 형태의 시안이 들어오든 구현이 끝나면 코드가 source of truth가 됩니다.

가역성 기반 의사결정

모든 작업은 3단계 가역성으로 분류됩니다.

등급	의미	처리
R0	로컬 변경, 즉시 되돌림 가능	자동 실행
R1	되돌릴 수 있으나 비용 큼	사람 승인 필요
R2	데이터 손실, 외부 상태 변경	확인 문구 재입력 필요

최소 발자국

• 과도한 엔지니어링 금지 — 현재 요구사항에 필요한 최소 복잡도
• 비슷한 코드 3줄 이하는 추상화 금지
• 미래 요구사항을 위한 설계 금지
• 범위 외 파일 수정 금지

방향성

AI Agent를 “도구”가 아닌 “팀원”으로

32개 에이전트가 각각 역할을 가지고 있습니다. planner가 계획하고, builder가 구현하고, investigator가 디버깅하고, code-reviewer가 검증합니다. 사람은 의사결정과 에스컬레이션에 집중합니다.

규칙의 3계층

규칙은 Universal, Company, Personal 세 계층으로 나뉩니다. 이 문서에서는 왜 계층을 나누는지만 다루고, 실제 배포 대상과 예시는 시스템 아키텍처에서 관리합니다.

멀티 도구 통합

Claude Code와 Codex는 같은 원칙과 스킬을 공유해야 합니다. 구체적인 동기화 절차와 경로 포터블화는 크로스 도구 동기화에서 별도로 추적합니다.