Adept

Adept는 조직의 인지 부채를 정량적으로 계측하고 관리하는 감사 프레임워크입니다. 시스템 사양과 코드가 고도화되는 환경에서, 단순 문서 열람 여부가 아닌 산출물의 실제 기술 명세를 바탕으로 구성된 평가 문항 통과 여부를 통해 공학적 Vouch를 측정합니다.

Adept는 지식 공유 계층을 기준 원장(Ledger)으로 운용합니다:

• 분모(필수 인지 지식): adept.manifest.yaml에 등록된 핵심 아티팩트 집합
• 분자(검증된 이해도): 유효한 엔지니어 서약 상태를 유지하는 아티팩트 집합
• 인지 부채(Cognitive Debt): 분모와 분자의 차이((1 - \text{Coverage})), 즉 현재 유효한 보증자가 부재한 미보증 아티팩트의 결손량

핵심 개념

• 엔지니어 서약 수명주기 및 불변성 — 검증된 이해 평가는 대상 아티팩트의 content_hash에 바인딩됩니다. 아티팩트 내용이 변경되면 기존 엔지니어 서약은 즉시 스테일 상태로 전이되어 이전 사양에 대한 이해가 자동으로 이월되지 않습니다.
• 간격 반복 평가 (Spaced Repetition) — 문항별 숙련도와 시간 경과에 따라 재평가 주기를 산출하며, 주기 도래 시 재검증을 요구합니다.
• Vouch 커버리지 및 미보증 핫리스트 — 조직 전체의 핵심 아티팩트 대비 유효 엔지니어 서약 비율을 산출하고, 보증자가 전무한 아티팩트를 핫리스트로 우선 분류하여 지식 결손을 사전 방지합니다.
• 작성자 중립성 — 작성 주체(인간 엔지니어 또는 자율 코딩 에이전트)와 무관하게, 현재 시점에서 해당 사양을 책임지고 설명할 수 있는 담당자의 존재 여부만을 평가합니다.

실행 및 CLI 인터페이스

uv tool install ./adept    # 전역 CLI 도구 설치 (또는 pipx install ./adept)

adept.manifest.yaml이 위치한 프로젝트 루트 또는 하위 경로에서 실행합니다:

adept register PATH                    # 핵심 아티팩트 등록 (artifact_id 발급)
adept due --as PERSON                  # 평가 주기 도래 문항 및 평가 필요 아티팩트 조회
adept coverage --as PERSON             # 조직 Vouch 커버리지, 미보증 핫리스트, 취약 영역 출력
adept review ARTIFACT_ID --as PERSON   # 헤드리스 평가 세션 실행 (ANTHROPIC_API_KEY 필요)

팀 단위 협업 및 대시보드 인터페이스는 웹 기반 UI와 공유 저장소 백엔드를 제공하는 adept-web을 통해 지원됩니다.