계획 검토 및 감사 내역

사용자 목표 및 워크플로 경계

이 실용적인 워크플로는 개발자와 검토 에이전트가 리포지토리의 실증적 증거를 바탕으로 소프트웨어 제안, 기술 사양 및 아키텍처 계획을 감사하는 과정을 안내합니다. 검토자는 계획의 주장을 저장된 프로젝트 제약 조건과 비교하고, 개별 라이프사이클 단계(planned, submitted, merged, released, verified)에 걸친 변경 사항을 추적하며, 승인된 합의 결정을 변경 불가능한 출처 귀속과 함께 유지 관리합니다.

이용 가능성 및 사전 요구 사항

감사 및 계획 검토 기능은 MCP 클라이언트 프로필과 독립형 Skill CLI 전반에서 제공됩니다:

• MCP cursor-plugin 및 ordinary-full 프로필: 포괄적인 검토 기능을 제공합니다: get_project_context(읽기 전용 프로젝트 팩), recall_context, search_knowledge, update_project_decision(결정 상태 전환: resolve, supersede, reopen), update_project_todo(작업 항목 상태 전환: accept, assign, block, unblock, complete, cancel), query_audit(이벤트 및 통합 기록 감사).
• MCP claude-plugin 프로필: get_project_context, recall_context, create_pending_decision, resolve_decision, record_event, remember, recall, todo를 포함합니다.
• MCP generic-public, chatgpt-public, public-only 프로필: 빠른 요약을 위한 focus="blockers" 또는 focus="status" 매개변수를 지원하는 get_project_summary(project_id, focus)와 통계를 위한 memory_overview를 지원합니다.
• 독립형 Skill(Claude Code, Codex, OpenClaw): 제공되는 1.1.35 help.mjs의 축자 명령어: recall-context(84-87줄), search(80-83줄), remember(72-75줄), update(44-47줄), todo-add/list/done(112-123줄), activity/stats(64-71줄).
• 사전 요구 사항: 프로젝트 컨텍스트 및 감사 기록을 쿼리하기 위한 읽기 범위(memory:read), 결정을 기록하고 작업 항목을 업데이트하기 위한 쓰기 범위(memory:write).

단일 완료 작업: 서비스 마이그레이션 계획 감사

이 합성 감사 연습에서는 에이전트가 proj_security_core 프로젝트의 인증 업그레이드 제안을 검토하고, 리포지토리 제약 조건에 대해 주장을 검증하며, 작업 항목 상태를 전환하고 승인된 결과를 저장합니다.

프로젝트 제약 조건 및 감사 기록 검색

recall-context 또는 get_project_context를 사용하여 확립된 프로젝트 지침을 검색하고 이전 결정 출처를 검사합니다:

node scripts/xmemo-skill.mjs recall-context --query "token revocation policy session lifetime proj_security_core" --max_items 6 --max_tokens 2500

작업 항목 상태 전환 및 결정 기록

검토 TODO를 완료로 표시하고 출처와 함께 신뢰할 수 있는 해결책을 저장합니다:

node scripts/xmemo-skill.mjs todo-done --id todo_rev_401
node scripts/xmemo-skill.mjs remember --content "Approved plan auth_migration_v3: enforced 24h token revocation, strict mutual TLS, and zero unauthenticated fallback. Verified by reviewer audit." --path "plans/auth_migration_v3"

관찰 가능한 결과

구조화된 계획 감사는 개별 라이프사이클 마일스톤을 반영하는 변경 불가능하고 검증 가능한 감사 내역을 생성합니다:

• 5가지 고유한 마일스톤 상태: 계획과 작업 항목은 명시적인 단계를 거쳐 진행됩니다: planned(초안 작성된 사양) -> submitted(공식 검토 요청됨) -> merged(구현 통합됨) -> released(패키징 및 배포됨) -> verified(배포 후 검증 통과). planned를 released 또는 verified와 혼동하지 마십시오.
• 결정론적 감사 추적: query_audit은 이벤트 타임스탬프, 실행 에이전트의 agent_id, 대상 메모리/결정 ID, 변경 전후의 상태 차이(diff)를 포함하는 구조화된 레코드를 반환합니다.
• 출처 보존: recall 또는 recall_context로 메모리를 쿼리할 때 결과에는 정확한 권한 부여 세션 및 타임스탬프를 식별하는 변경 불가능한 출처 메타데이터가 노출됩니다.

에이전트가 액세스할 수 있는 항목

계획 검토 및 감사를 수행하는 에이전트는 구조화되고 범위가 지정된 표현과 상호 작용합니다:

• 추가 전용 감사 로그: 감사 이벤트 로그는 추가 전용(append-only)입니다. 에이전트는 과거의 결정 감사 기록을 덮어쓰거나 변조하거나 삭제할 수 없습니다.
• 버전 DAG 및 대체(supersession): 기존 결정이나 메모리를 업데이트하면 이전 항목에 연결된 새 버전이 생성됩니다. 이전 상태는 대체된 버전으로 계속 검색할 수 있습니다(cursor-plugin / ordinary-full의 list_memory_versions).
• 증거 기반 컨텍스트: recall 도구는 프로젝트 메모리에서 추출된 사실적 증거를 반환하여 에이전트가 검증되지 않은 모델 추론을 기록된 프로젝트 결정으로 오인하는 것을 방지합니다.

공유 및 스토리지 경계

감사 기록과 결정은 엄격한 다중 테넌트 및 프로젝트 파티션에 의해 제어됩니다:

• 프로젝트 범위 경계: project:proj_security_core에 바인딩된 결정 및 작업 항목은 관련 없는 개인 프로젝트나 외부 팀 공간으로부터 격리된 상태로 유지됩니다.
• 임시 메모 제외: 임시 개발자 메모(scratchpad), 로컬 디버깅 로그 및 일시적인 생각은 지속성 결정 레코드에 기록되어서는 안 됩니다.
• 귀속 불변성: 서버는 인증된 호출자의 owner_identity 및 source_identity를 모든 결정에 스탬프합니다. 클라이언트는 다른 에이전트를 위조하거나 가장할 수 없습니다.

오류 복구

표준 해결 경로를 사용하여 감사 불일치 및 검토 충돌을 관리합니다:

• 검증되지 않은 계획 주장 또는 모순: 제안된 계획이 기존 아키텍처 결정과 모순되는 경우 결정을 해결하지 마십시오. 불일치를 설명하는 자세한 resolution_note와 함께 action="supersede" 또는 action="reopen"으로 결정을 전환합니다.
• 작업 항목 또는 결정 ID 누락: 참조된 todo_id 또는 decision_id를 찾을 수 없는 경우 todo-list(Skill) 또는 get_project_context(project_id="proj_security_core")를 사용하여 활성 항목을 쿼리하여 표준 ID를 찾습니다.
• 범위 권한 거부: 에이전트에 대상 프로젝트에 대한 쓰기 권한이 없는 경우 update_project_decision은 HTTP 403 Forbidden을 반환합니다. 역할 할당을 위해 프로젝트 관리자에게 에스컬레이션하십시오.

관련 참조

관련 보안 개념, 출처 세부 정보 및 작업 항목 관리에 대해서는 다음 가이드를 참조하십시오:

• 출처 및 귀속: 호출자 귀속 세부 정보는 /docs/concepts/provenance-attribution을 참조하십시오.
• TODO 작업 항목 참조: 프로젝트 작업 추적은 /docs/tools/todos를 참조하십시오.
• 원장 거래 참조: 재무 및 리소스 감사는 /docs/tools/ledger를 참조하십시오.
• 재개 및 에이전트 인수인계: 세션 체크포인트 생성 워크플로는 /docs/guides/resume-and-handoff를 참조하십시오.
• 프로젝트 가이드: 프로젝트 워크스페이스 조직화는 /docs/concepts/projects를 참조하십시오.