참새 AI 문서

이 저장소는 YouTube 영상의 미디어 조작 가능성과 영상 속 주장의 사실성을 분석하는 참새 AI의 기획, 설계, 검증 및 의사결정 기록을 관리한다.

프로젝트는 Wanted AI Championship 2026 출품을 목표로 진행한다.

현재 일정과 진행 현황은 프로젝트 계획에서 확인한다. MVP 결정 기록과 남은 기술 검증 항목은 MVP 검토 목록에 모았다.

현재 프론트 배포 주소는 서비스 접속이다.

팀 구성

이름	직책
조정준	팀장
나정균	팀원

문서 구조

현재 필요한 문서부터 작성하고, 반복되는 기록이나 독립적인 검토가 필요한 시점에 디렉터리와 파일을 추가한다. 아래에서 (예정)으로 표시한 항목은 생성 조건을 충족할 때 만든다.

.
├── AGENTS.md                       # 에이전트가 항상 따르는 문서 작성 규칙
├── CLAUDE.md                       # AGENTS.md 를 가리키는 심볼릭 링크
├── README.md
├── .agents/
│   └── skills/                     # 반복 작업을 위한 Skill 원본
│       ├── commit/
│       │   └── SKILL.md
│       ├── pr/
│       │   └── SKILL.md
│       ├── reconcile-docs/
│       │   └── SKILL.md
│       └── refine-doc/
│           └── SKILL.md
├── .claude/
│   └── skills/                     # .agents/skills 의 각 Skill을 가리키는 심볼릭 링크
├── .github/
│   └── pull_request_template.md    # 문서 PR 본문 틀
├── .vscode/
│   └── settings.json               # 마크다운 저장 시 포맷 비활성화
├── project/                         # 제품 범위와 프로젝트 운영 기준
│   ├── assumptions.md               # 문제·사용자·범위와 초기 구현 가정
│   ├── mvp-review.md                # MVP 결정 기록과 남은 기술 검증 항목
│   ├── prd.md                       # 문제 정의, 사용자, 요구사항, MVP 범위
│   └── project-plan.md              # 역할, 마일스톤, 일정, 위험
├── design/                          # 제품과 AI 시스템 설계
│   ├── system-overview.md           # FE, BE, AI 파이프라인의 전체 구성 (예정)
│   ├── ai-pipeline.md               # 단계별 AI 처리, 후보 기술, 평가 기준
│   ├── analysis-runtime.md          # 분석 실행 구조, 상태, 처리량과 확장 기준
│   ├── evidence-policy.md           # 주장 근거 선택, 출처 충돌과 판정 기준
│   └── result-ui.md                 # 분석 진행, 순차 결과와 최종 요약 UI 흐름
├── evaluations/                     # 모델·기능 테스트와 점검 기록
│   ├── claim-verification-pipeline.md
│   ├── deepfake-detection-model-comparison.md
│   ├── factcheck-method-options.md
│   ├── frame-aggregation-comparison.md
│   ├── implementation-notes.md
│   ├── license-and-terms.md
│   ├── mvp-acceptance.md
│   └── mvp-implementation-audit.md
├── templates/                       # 반복 작성하는 문서의 공통 골격
│   └── meeting.md                   # 회의록 템플릿
├── meetings/                        # 회의별 논의와 결정 기록
│   ├── 2026-09-03-kickoff.md
│   ├── 2026-09-05-progress.md
│   ├── 2026-09-11-progress.md
│   └── 2026-09-13-integration.md
└── adr/                             # 확정된 주요 기술 결정 (예정)

Skill 원본은 .agents/skills/에 두고 .claude/skills/에는 같은 이름의 심볼릭 링크를 둔다. 도구마다 Skill을 찾는 경로가 달라 두 경로가 모두 필요하지만, 내용은 원본 한 곳에서만 관리한다. 링크는 상대 경로로 걸어 저장소 위치와 무관하게 동작한다. CLAUDE.md도 같은 이유로 AGENTS.md를 가리키는 심볼릭 링크이며, 문서 작성 규칙 본문은 AGENTS.md에만 둔다.

project/prd.md, project/project-plan.md, project/mvp-review.md, design/ai-pipeline.md, design/analysis-runtime.md와 design/result-ui.md는 초안을 작성 중이다. project/assumptions.md와 design/evidence-policy.md는 합의한 현재 기준으로 사용한다. 나머지 예정 문서는 필요한 시점에 생성한다. 빈 디렉터리나 내용 없는 문서를 구조 유지 목적으로 추가하지 않는다.

리뷰 약속 반영

PR·댓글·커밋을 대조하고 기준 문서·미결 표·충돌을 정리할 때 reconcile-docs 스킬을 사용한다. 원본은 .agents/skills/reconcile-docs이며 .claude/skills/reconcile-docs도 같은 파일을 참조한다. 문서 링크·절·표·연속 빈 줄 검사는 저장소 루트에서 다음과 같이 실행한다.

python3 .agents/skills/reconcile-docs/scripts/check_docs.py --base origin/main

문서별 책임

위치	다루는 내용	다루지 않는 내용
project/assumptions.md	문제의식, 사용자·범위와 초기 구현 방향의 가정	확인된 사실, MVP 요구사항과 성공 기준
project/mvp-review.md	MVP 결정 기록, 항목별 상태와 남은 기술 검증 범위	현재 요구사항의 상세 명세, 일정별 진행 현황
project/prd.md	문제 정의, 목표 사용자, 사용자 시나리오, 요구사항, MVP와 제외 범위, 성공 기준	기술 구현 상세, 일정별 작업 현황
project/project-plan.md	역할, 마일스톤, 일정, 작업 기준, 일정 위험	회의 당시의 대화, 상세 기능 명세
design/system-overview.md	FE, BE, AI 분석 구성요소의 책임과 데이터 흐름	모델별 실험 결과, 작업 일정
design/ai-pipeline.md	영상 확보부터 미디어 조작 탐지와 주장 검증까지의 처리 단계	제품 요구사항 원문, 확정된 결정의 이력
design/analysis-runtime.md	작업 대기열과 Worker, 실행 상태, 동시 처리, 성능 측정과 확장 기준	단계별 분석 방법, 제품 요구사항 원문
design/evidence-policy.md	주장과 근거의 관련성·시점·출처 확인, 판정과 출처 충돌 처리 기준	검색·판정 기술 선정, 모델별 실험 결과
design/result-ui.md	진행 상태, 주장 카드의 순차 갱신, 미디어 조작 결과와 최종 요약 흐름	API·모델 구현 상세, 제품 요구사항 원문
evaluations/	모델·기능 테스트 결과, 점검과 인수 기록, 사용 조건 확인	제품 결정의 기준 원문, 일정별 진행 현황
meetings/	회의 시점의 논의, 결정 사항, 미결 사항, 액션 아이템	변경되는 최신 일정과 제품 기준
adr/	되돌리기 어렵거나 영향 범위가 큰 기술 결정과 근거	후보 기술 전체의 상세 비교, 회의 전체 내용
templates/	반복 작성하는 문서의 필수 항목과 공통 구조	프로젝트의 실제 내용과 확정된 결정

회의록은 특정 시점의 기록으로 유지한다. 회의에서 제품 범위나 일정이 변경되면 결정 사실은 회의록에 남기고, 현재 기준은 prd.md 또는 project-plan.md에 반영한다.

핵심 설계 경계

제품은 다음 두 분석 결과를 구분한다.

1. 미디어 조작 탐지: 인물의 얼굴 합성·변형을 분석하고, 업로더가 제목이나 설명에 적은 AI·합성 표기를 함께 전달한다.
2. 주장 사실성 검증: 영상에서 검증 가능한 주장을 추출하고 외부 근거와 비교한다.

두 결과는 하나의 진위 판정으로 취급하지 않는다. 실제 인물이 등장한 영상에도 허위 주장이 포함될 수 있고, 합성된 영상의 발언 내용이 사실일 수도 있기 때문이다. 제품 표시 방식은 prd.md에서, 처리 방식은 ai-pipeline.md에서 정의한다.

문서 분리 기준

단일 파일로 유지하는 경우

• 같은 목적과 결론을 향하는 내용이다.
• 한 흐름으로 읽어야 문맥이 유지된다.
• 담당자와 변경 주기가 같다.
• 문서 전체에 하나의 상태를 부여할 수 있다.

초기 PRD, 프로젝트 계획, 시스템 개요, AI 파이프라인은 각각 단일 파일로 시작한다.

여러 파일로 분리하는 경우

다음 조건 중 두 개 이상에 해당하면 기존 문서를 분리한다.

• 서로 다른 담당자가 독립적으로 수정한다.
• 일부 내용만 별도의 검토나 승인이 필요하다.
• 변경 주기가 다른 내용이 한 파일에 섞여 있다.
• 개별 문서를 다른 문서에서 반복해서 참조한다.
• 하나의 상태로 관리할 수 없는 항목이 함께 들어 있다.
• 같은 형식의 기록이 계속 추가된다.

회의록과 ADR은 작성 시점과 상태가 각각 다르므로 처음부터 파일을 나눈다. 파일 길이는 보조 판단 기준으로만 사용한다.

필요할 때 추가하는 문서

다음 디렉터리는 현재 만들지 않는다. 각 생성 조건이 발생하면 첫 문서와 함께 추가한다.

디렉터리	생성 조건	파일 단위
evaluations/	Playground에서 모델, 오픈소스 또는 외부 API 비교 실험을 시작할 때	평가 주제 하나당 한 파일
rfcs/	여러 저장소나 담당자에게 영향을 주는 설계 변경에 사전 합의가 필요할 때	제안 하나당 한 파일
submission/	대회 제출 내용과 데모 시나리오를 조립하기 시작할 때	제출물 종류별 한 파일

실험 코드, 샘플 입력 및 실행 스크립트는 Playground 저장소에서 관리한다. evaluations/에는 실험 목적, 조건, 지표, 결과, 해석과 재현 경로를 기록한다.

문서와 개발 기록의 관계

기록	관리 위치
문제·사용자·범위와 초기 구현 가정	project/assumptions.md
제품 요구사항과 MVP 범위	project/prd.md
일정과 역할의 현재 기준	project/project-plan.md
시스템 및 AI 처리 설계	design/
기술 후보 비교와 실험 결과	evaluations/
확정된 주요 기술 결정	adr/
회의 당시의 논의와 액션 아이템	meetings/
구현 작업과 완료 조건	관리 방식 미정
코드 변경 이유와 검증 결과	각 개발 저장소의 Pull Request

브랜치 운영

• 작업 브랜치는 main에서 분기하며 docs/<작업 주제> 형식으로 이름을 짓는다.
• 작업 주제는 영문 소문자와 하이픈으로 작성한다. 예: docs/initial-planning, docs/pr-workflow.
• 하나의 브랜치와 PR에는 함께 검토할 변경만 포함하고, 커밋은 변경 목적별로 나눈다.
• 독립적인 PR은 같은 기준의 main에서 분기해 서로의 변경을 포함하지 않는다. 의존 관계가 있으면 PR에 명시한다.
• PR 생성 순서와 병합 순서는 구분한다. 독립적인 PR의 병합 순서는 검토 상황에 따라 정한다.

작성 규칙

• 저장소 전체의 상세 작성 규칙은 AGENTS.md를 따른다.
• 파일명은 영문 소문자와 하이픈을 사용한다.
• 회의록은 YYYY-MM-DD-topic.md 형식을 사용한다.
• ADR은 NNN-decision-title.md 형식을 사용한다.
• 문서 본문은 평서체로 통일한다.
• 표의 각 열에는 하나의 독립된 속성만 기록한다. 상태·시점, 담당자·기한, 근거·결정일처럼 별도로 갱신하는 값은 각각 다른 열에 둔다.
• 코드 블록 내부를 제외하고 문서 요소 사이의 빈 줄은 한 줄만 사용하며, 편집 후 연속 빈 줄이 남지 않았는지 확인한다.
• 범위를 나타내는 ~ 앞뒤에는 공백을 둔다. 예: M-01 ~ M-08, 1 ~ 2초.
• 같은 내용을 여러 문서에 복사하지 않고 기준 문서를 링크한다.
• 사실, 결정, 가설과 미결 사항을 구분해서 작성한다.
• 수치에는 측정 조건이나 출처를 함께 기록한다.
• 외부 자료, 모델, API와 오픈소스에는 출처 및 라이선스를 기록한다.
• 문서 변경도 Pull Request에서 검토한다.

문서 상태

검토와 합의가 필요한 문서에는 문서 상단에 상태를 기록한다. 상태 라벨은 백틱으로 감싸며, - 상태: 뒤에 Draft와 같이 표기한다.

상태	의미
Draft	초안 작성 중이며 기준으로 사용하지 않는다.
In Review	팀 검토 중이다.
Accepted	팀이 합의한 현재 기준이다.
Superseded	다른 문서나 결정으로 대체되었다.

회의록과 평가 결과처럼 특정 시점의 사실을 기록하는 문서에는 상태를 생략할 수 있다.