av/facts

facts란?

av/facts는 프로젝트를 .facts 파일의 원자적 주장 목록으로 관리하는 워크플로우이자 명세 형식입니다. 각 줄은 참이어야 할 짧고 구조화된 진술이며, 선택적으로 기계가 주장을 검증하기 위해 실행하는 shell command를 포함할 수 있습니다.

핵심 목적은 에이전트와 팀이 프로젝트 요구사항을 읽기 쉽고 검증 가능하게 유지하는 것입니다: 대략적인 진실을 작성하고, 이를 정밀한 명세로 다듬은 후 구현하고 검증합니다. facts check를 실행하면 어떤 주장이 통과, 실패, 또는 수동 주의가 필요한지 확인할 수 있습니다.

주요 기능

• 원자적 “fact” 명세 형식 (.facts): 도메인별 Markdown 제목으로 정리된 평문 문자열로 줄당 하나의 주장을 작성합니다.
• 진행 상황 추적을 위한 라이프사이클 태깅: @draft, @spec, @implemented (및 사용자 정의 태그)를 사용해 각 주장의 파이프라인 위치를 표시합니다.
• 명령어 기반 검증: command를 포함한 fact에 대해 facts check가 명령어를 실행하고, 명령어가 0으로 종료되면 주장을 참으로 간주합니다.
• 자동 검증 및 상태 그룹화: facts check가 파일을 린트하고 모든 명령어를 실행하며 결과를 그룹화합니다 (예: 녹색 통과, 빨간색 실패, 노란색 수동); 실패 시 0이 아닌 코드로 종료합니다.
• CI 친화적 종료 코드 및 필터링: 태그 표현식으로 체크를 필터링합니다 (예: --tags "mvp and not blocked")하여 명세의 부분 집합을 검증합니다.
• 에이전트 관리 전환 및 명세에 대한 구현: 에이전트가 fact 시트를 읽고 @spec fact를 선택해 빌드한 후 facts check를 실행하고, 통과한 fact를 @implemented로 태깅하며 명세를 스스로 업데이트합니다.

facts 사용 방법

1. CLI/에이전트 도구 설치 (프로젝트가 Rust 바이너리 및 아래 설명된 npx 명령어를 포함한 여러 설치 옵션을 제공합니다).
   • 예: npx skills add av/facts
   • 그런 다음 에이전트에게 Init facts 실행을 요청합니다 (예: “Init facts”)하여 스택을 감지하고 초기 .facts 파일을 생성합니다.
2. 문서화된 형식으로 .facts 파일 생성 또는 편집:
   • 도메인별로 제목 추가 (예: # auth, # data).
   • 줄당 하나의 주장 추가.
   • @draft, @spec, @implemented 등의 라이프사이클 단계 레이블로 각 fact 태깅.
   • 검증 가능한 주장에는 주장이 성립할 때 0으로 종료하는 command 포함.
3. 검증 실행: facts check로 모든 fact를 린트하고 검증합니다 (또는 --tags로 체크 제한). 통과, 실패, 수동 작업이 필요한 항목 검토.
4. 에이전트와 반복: @draft로 대략적인 아이디어 작성, @spec로 다듬은 후 에이전트가 @spec fact를 구현하고 facts check 통과 시 @implemented로 태깅.

사용 사례

• 변경 후 프로젝트 명세 검증: 참이어야 할 살아있는 체크리스트를 유지하고 편집 후 facts check를 실행해 여전히 성립하는 항목을 빠르게 확인.
• 요구사항을 실행 가능 체크로 전환: 인증 동작이나 데이터 처리 규칙 같은 “참이어야 함” 진술을 명령어 기반 검증이 포함된 fact로 변환.
• fact 라이프사이클로 작업 진행 관리: @draft → @spec → @implemented를 사용해 진행 상황 전달하고, 각 주장이 구현/검증되었거나 명확히 다듬기 표시.
• 자동 코드베이스 발견 및 분류: facts-discover 스킬로 코드베이스를 스캔하고 라이프사이클 단계별로 fact 분류, 누락된 진실 추가.
• 명세에 대한 구현: 에이전트가 @spec fact를 읽고 코드 빌드, facts check로 검증 후 태그 업데이트하는 facts-implement 흐름 사용.

자주 묻는 질문

facts는 단순 문서 형식인가, 실제로 주장을 검증하나요? 둘 다 가능합니다: 명령어가 없는 fact는 에이전트가 코드베이스에 대해 검증하고, command가 있는 fact는 명령어 실행과 종료 코드 0 확인으로 검증합니다.

facts check는 무엇을 하나요? 파일 린트, 제공된 모든 명령어 실행, 상태(통과/실패/수동)별 결과 그룹화, 실패 시 0이 아닌 코드로 종료합니다.

fact는 어떻게 구성되고 추적하나요? Markdown/YAML 호환 구조의 .facts 파일에 저장되며, 도메인 조직을 위한 제목과 라이프사이클 상태 추적을 위한 태그(@draft, @spec, @implemented 포함)를 사용합니다.

프로젝트 일부만 체크할 수 있나요? 네. facts check는 --tags로 불리언 표현식을 통한 태그 필터링을 지원합니다.

대안

• 테스트 스위트 (단위/통합 테스트): 전통 테스트는 동작 검증 가능하지만, .facts 체크리스트는 인간 읽기 쉬운 원자적 주장과 라이프사이클/상태 파이프라인을 강조하며 단순 자동 통과/실패가 아닙니다.
• 정적 문서 + 코드 리뷰: 문서는 요구사항 캡처 가능하지만 직접 실행되지 않습니다; facts는 facts check를 통해 주장을 검증에 연결합니다.
• 요구사항 추적성을 지원하는 명세 도구: 구현과 요구사항을 연결하는 도구는 추적성을 제공할 수 있지만, facts는 선택적 명령어 실행과 태그 기반 라이프사이클 전환을 가진 줄별 주장 형식을 사용합니다.