docs

Imported from yonghun16/bingo (docs/AGENTS.md). Install upstream with npx skills add yonghun16/bingo --skill docs. Copyright stays with the author.

AGENTS.md

📌 이 파일은 보일러플레이트입니다. [[ ]]로 표시된 부분만 프로젝트에 맞게 채우고, 그 외 규칙은 프로젝트가 바뀌어도 그대로 유지하세요. 이 파일 자체를 프로젝트마다 새로 설계하지 않는 것이 목적입니다.

이 저장소의 docs/ 폴더 안에는 성격이 다른 세 개의 시스템이 공존할 수 있습니다. 작업 전 반드시 어느 쪽에 해당하는지 먼저 판단하세요.

시스템	위치	관리 도구	용도
Vault (일반 문서)	docs/content/	사람이 직접 작성 + Obsidian/Quartz	기획, 개발 프로세스, 회의/결정 기록 등
Spec (기획/계획서)	docs/specs/	LeanSpec CLI/MCP 전용	기능 단위 스펙, 진행 상태 추적
ADR (의사결정 기록)	docs/decisions/	사람/AI가 직접 작성 (파일 추가만, 수정 금지)	왜 이 방향으로 결정했는지의 역사

이 셋은 frontmatter 스키마도, 편집 방식도 다릅니다. 섞어 쓰지 마세요.

저장소 전체가 문서 전용이면 저장소 루트에 AGENTS.md로 두고, 코드와 문서가 함께 있는 모노레포라면 문서 폴더 쪽(예: docs/AGENTS.md — docs/content/ 안이 아니라 docs/ 바로 아래, Quartz 설정과 같은 위치)에 이 파일을 두세요. Claude Code 등은 이런 설정 파일을 계층적으로 읽으므로, 그 폴더 하위에서 작업할 때는 저장소 루트의 파일과 이 파일이 함께 적용됩니다 — 그러니 루트 쪽에는 코드/문서 폴더 경계 정도만 남기고, 문서 작성 세부 규칙은 여기 한 곳에만 두는 것을 권장합니다.

LeanSpec을 사용하는 경우, leanspec init이 이 파일명(AGENTS.md)으로 자체 규칙을 자동 생성/재생성할 수 있습니다. 그러니 이 통합 보일러플레이트를 쓸 때도 파일명은 CLAUDE.md가 아니라 AGENTS.md로 유지하세요. 그래야 LeanSpec 관련 명령을 다시 실행해도 규칙이 다시 흩어지지 않습니다.

문서를 AI(Claude)가 함께 쓰고 정리하는 것을 전제로, 사람이 읽기 좋을 뿐 아니라 나중에 AI 에이전트가 검색·인용·재사용하기도 좋은 방식 (메타데이터, 자기완결적 문단, 최신성 관리 등)을 함께 반영했습니다.

한 번 정하고 넘어가는 값은 아래 "프로젝트 설정" 섹션에 모아뒀습니다.

프로젝트 설정 (새 프로젝트 시작 시 여기만 채우면 됩니다)

프로젝트 개요

[[Bingo 게임의 기획/개발 문서를 관리하는 Obsidian Vault입니다. Quartz 5로 정적 사이트를 빌드해 퍼블리시하고, 기능 단위 스펙은 LeanSpec으로 관리합니다.]]

문서 폴더 추가

[[기획/, 개발/, private/ 외에 프로젝트 성격에 따라 필요한 주제별 문서 폴더를 추가 (예: 운영/, 회의록/) — "3. Vault 문서 관리 > 폴더 구조" 섹션에서 사용]]

1. Spec 관리 (docs/specs/ — LeanSpec)

LeanSpec을 쓰지 않는 프로젝트라면 이 섹션 전체를 삭제해도 됩니다.

🚨 CRITICAL: 스펙 작업 전 반드시 먼저 할 것

1. Discover context → board 도구로 프로젝트 현황 확인
2. Search for related work → search 도구로 기존 스펙 먼저 확인
3. Never create files manually → 새 스펙은 항상 create 도구로 생성

이유: 탐색을 건너뛰면 중복 작업이 생기고, 파일을 수동으로 만들면 LeanSpec 툴링이 깨집니다.

MCP 도구 (권장) + CLI 폴백

[[MCP 서버를 등록했다면 "MCP Tools 우선", CLI만 쓰고 있다면 "CLI Fallback만 사용 중"이라고 이 자리에 현재 상태를 적어두세요.]]

⚠️ Spec 핵심 규칙

🚫 흔한 실수

SDD 워크플로우

BEFORE: board → search → 기존 스펙 확인
DURING: 상태를 in-progress로 갱신 → 코딩 → 결정사항 문서화 → 의존성 연결
AFTER:  완료 내용 문서화 → 상태를 complete로 갱신

상태는 구현 진행도를 추적하는 것이지, 스펙 작성 여부가 아닙니다.

스펙 작성 여부 판단

토큰 임계값

작업 완료 전 검증:

lean-spec validate              # 구조·품질 확인
lean-spec validate --check-deps # 의존성 정합성 확인

Spec 작성 원칙 (First Principles)

1. Context Economy — 2,000 토큰 이하가 최적, 3,500 넘으면 분리
2. Signal-to-Noise — 모든 문장이 결정에 도움이 되어야 함
3. Intent Over Implementation — "왜"를 담고 "어떻게"는 흘러나오게
4. Bridge the Gap — 사람과 AI 모두 이해 가능해야 함
5. Progressive Disclosure — 필요성이 느껴질 때만 복잡도 추가

2. 의사결정 기록 (docs/decisions/ — ADR)

아키텍처, 기술 스택, 설계 방향에 대한 중요한 결정을 내리거나 기존 결정을 뒤집을 때마다, docs/decisions/ 폴더에 새 md 파일을 만들어 기록합니다.

• 파일명: NNNN-짧은-제목.md (번호는 순차 증가)
• 기존 결정 파일은 절대 수정하지 않고, 바뀌면 새 파일에 "이전 결정(0003)을 대체함"이라고 명시
• 내용 구조:
  • Context: 왜 이 결정을 고민하게 됐는지
  • Decision: 뭘로 결정했는지
  • Consequences: 트레이드오프, 앞으로 영향받는 부분

Spec(docs/specs/)이 "무엇을 만들지"를 다룬다면, ADR(docs/decisions/)은 "왜 이 방향으로 정했는지"의 역사를 남깁니다. 둘은 서로 다른 목적이므로 혼동하지 마세요.

3. Vault 문서 관리 (docs/content/ — Obsidian / Quartz)

프로젝트 문서(기획, 구현 프롬프트, 개발 프로세스, 회의/결정 기록 등)는 docs/content/(Obsidian Vault, Quartz 5로 사이트 빌드)에서 관리되는 마크다운 파일로 작성합니다. docs/ 폴더에는 Quartz 5 관련 설정/코드와 docs/specs/, docs/decisions/가 함께 있을 수 있으므로, Vault(일반 문서)는 반드시 docs/content/ 하위에만 작성하고 docs/ 바로 아래(Quartz 설정 파일들이 있는 위치)에는 문서를 두지 않습니다.

폴더 구조

• folder-page가 켜져 있으므로 폴더 자체가 목록 페이지가 됩니다. 문서를 docs/content/ 바로 아래에 평평하게 흩어놓지 말고, 반드시 주제별 폴더로 묶어서 넣습니다.
  • 기획/ — 요구사항, 기능 정의 등 기획 문서
  • 개발/ — 개발 프로세스, 구현 프롬프트 등 개발 관련 문서
  • private/ — 초안/메모용. ignorePatterns에 이미 제외되어 있어 퍼블리시되지 않습니다. 아직 정리되지 않은 초안은 우선 여기에 둡니다.
  • (프로젝트별 추가 폴더는 최상단 "프로젝트 설정 > 문서 폴더 추가" 참고)
  • 새로운 주제가 생기면 임의로 루트에 파일을 만들지 말고, 어울리는 폴더가 없는지 먼저 확인하고 필요하면 새 폴더를 제안합니다.
• 파일명: 한글 파일명을 허용합니다 (예: 개발프로세스.md).

폴더 vs 태그

• 폴더는 큰 카테고리(기획/개발/회의록) 분류에만 사용합니다.
• 태그는 폴더를 가로지르는 속성에 사용합니다 (예: #스펙, #체크리스트, #진행중). tag-page가 켜져 있어 태그를 붙이면 자동으로 태그별 모음 페이지가 생성되므로, "이 문서는 어떤 성격인가"를 나타낼 때는 폴더를 새로 만들기보다 태그를 답니다.

문서 메타데이터 (Frontmatter)

모든 Vault 문서 최상단에 YAML frontmatter를 채웁니다 (LeanSpec 스펙과는 다른 스키마입니다 — 섞어 쓰지 마세요). Obsidian의 그래프/검색뿐 아니라, 나중에 이 Vault를 다시 열어보는 AI 에이전트가 본문을 다 읽지 않고도 문서의 성격과 최신성을 먼저 파악할 수 있게 하기 위해서입니다.

---
title: 문서 제목
description: 한두 문장 요약 (검색 결과·미리보기에 쓰입니다)
tags: [스펙, 체크리스트]
aliases: [이 문서를 부르는 다른 이름]
created: 2026-01-15
updated: 2026-01-15
status: draft   # draft | active | archived
---

• description은 본문 첫 문단을 그대로 복사하지 말고, 그 문서 하나만 봐도 무엇에 대한 문서인지 알 수 있게 요약합니다.
• 문서를 실질적으로 수정할 때마다 updated 값을 갱신합니다.
• 더 이상 유효하지 않은 문서는 "문서 최신성 관리" 섹션의 절차를 따릅니다.

문서 작성 원칙 (자기완결적으로 쓰기)

문서 하나, 섹션 하나가 전체 맥락 없이도 이해되도록 씁니다. 사람이 검색으로 문서 중간부터 읽고 들어오거나, AI 에이전트가 문서 전체가 아니라 일부 섹션만 참고하는 경우가 흔하기 때문입니다.

• 한 문서 = 한 주제. 여러 주제가 섞인 문서는 나중에 찾기도, 인용하기도, 업데이트하기도 어려워집니다. 문서가 커지면 하위 주제로 쪼개고 MOC로 연결합니다.
• "위에서 언급했듯이" 금지. 문서 내 다른 위치나 다른 문서를 전제로 하는 표현 대신, 필요하면 한두 문장으로 다시 짧게 설명하거나 [[문서명]] 링크로 대체합니다.
• 제목 구조를 일관되게. 문서당 H1(제목)은 하나이며 파일명과 의미가 일치해야 합니다. 그 아래 섹션 구분은 H2/H3로 통일합니다 — 나중에 특정 섹션만 잘라서 인용하거나 검색 결과에 노출될 때도 구조가 예측 가능하도록 하기 위해서입니다.
• 같은 사실을 여러 문서에 복사하지 않습니다. 이미 다른 문서에 정의된 내용(용어 정의, 결정 사항 등)은 복사해서 새로 쓰지 말고 [[문서명]] 링크로 참조합니다. 같은 내용이 여러 곳에 조금씩 다르게 적혀 있으면, 나중에 어느 쪽이 최신인지 알 수 없게 됩니다.
• 용어는 한 곳에서만 정의합니다. 반복적으로 쓰이는 도메인 용어는 별도 용어집 문서(예: 기획/용어집.md)에 정의하고, 다른 문서에서는 재정의하지 않고 링크만 겁니다.
• 한 화면을 넘기는 문서에는 상단에 짧은 요약(TL;DR)을 둡니다. frontmatter 바로 아래, 본문 시작 전에 2~3문장으로 핵심을 먼저 적습니다. 문서 전체를 읽지 않아도 요지를 파악할 수 있게 하기 위해서입니다. 아주 짧은 메모까지 요약을 강제할 필요는 없습니다.

MOC(허브) 패턴

• docs/content/index.md는 하위 문서들을 [[문서명]] 형태로 모아 링크하는 허브(MOC) 역할을 합니다. 새 문서를 추가하면 관련된 허브 문서(index.md 또는 하위 폴더의 허브 문서)에서 반드시 링크를 걸어줍니다.
• graph/backlinks 플러그인이 켜져 있어 링크를 많이 걸수록 그래프 뷰와 백링크 패널이 쓸모 있어집니다. 링크 없이 고립된 문서를 만들지 않습니다 — 새 문서를 만들면 최소 하나 이상의 다른 문서(허브 문서 또는 관련 문서)에서 링크로 연결되어 있는지 확인합니다.
• 문서 간 연관이 있으면 본문 중간에도 [[관련 문서명]] 링크를 적극적으로 겁니다.
• 내용이 어느 정도 있는 문서(짧은 메모 제외)에는 맨 아래에 ## 관련 문서 섹션을 두고, 본문 중간 링크와 별도로 핵심 관련 문서를 목록으로 한 번 더 모아줍니다. 이렇게 하면 문서를 끝까지 읽지 않고 관련 문서 목록만 봐도 전체 맥락을 파악할 수 있습니다.

문서 최신성 관리

AI가 여러 문서를 한꺼번에 다루다 보면 오래돼서 더 이상 맞지 않는 내용을 최신 내용과 똑같은 비중으로 참고하게 될 수 있습니다. 이를 막기 위해:

• 문서를 실질적으로 수정하면 frontmatter의 updated를 그 시점으로 갱신합니다.
• 더 이상 유효하지 않은 결정/스펙이 담긴 문서는 삭제하지 말고 frontmatter의 status를 archived로 바꿉니다 (히스토리 보존 목적). archived 문서는 MOC/허브 목록에서 "(archived)" 표시를 하거나 별도 섹션으로 분리합니다.
• 결정이 바뀌어서 기존 문서 내용이 틀려졌다면, 조용히 지우지 말고 문서 상단에 "(YYYY-MM-DD 기준 변경됨, [[새 문서명]] 참고)" 같은 안내를 남깁니다. (큰 방향 전환이라면 docs/decisions/에 ADR도 함께 남깁니다.)

옵시디언 전용 파일

• docs/content/.obsidian/, docs/content/templates/는 이미 ignorePatterns로 빌드에서 제외되어 사이트에 노출되지 않습니다. 옵시디언 설정이나 문서 템플릿은 그대로 저장소에 둬도 됩니다 (별도로 .gitignore 처리하거나 삭제할 필요 없음).

문서 종류 예시

• 구현 프롬프트 문서 (개발/): 특정 기능을 AI 코딩 툴에 맡길 때 사용한/사용할 프롬프트 원문을 그대로 보관합니다. 나중에 같은 기능을 다시 만들거나 다른 프로젝트에 재사용할 때 참고합니다.
• 개발 프로세스 문서 (개발/): 단계별 개발 순서, 완료 기준, 체크리스트 등을 기록합니다.
• 기획 문서 (기획/): 요구사항, 흐름, 기능 정의 등을 기록합니다.
• 초안/메모 (private/): 아직 정리되지 않았거나 외부에 공개하고 싶지 않은 내용.

AI가 새로운 프롬프트 문서나 프로세스 문서를 작성/수정할 때도 위 폴더 구조, 태그 사용법, frontmatter, MOC 링크 규칙을 따릅니다.

(선택) AI 에이전트를 위한 진입점 — llms.txt

Quartz로 빌드해 퍼블리시하는 사이트라면, 배포 결과물 루트에 llms.txt (핵심 문서 목록을 마크다운 링크로 정리한 짧은 색인 파일)를 두는 것을 고려할 수 있습니다. 이건 검색엔진 노출이나 "AI가 더 많이 인용해주는" 효과를 보장하는 표준이 아니라(실제로 그런 효과는 아직 근거가 약합니다), 나중에 이 사이트를 다시 방문하는 AI 에이전트(예: 새로운 Claude 세션)가 어디서부터 봐야 하는지 빠르게 파악하게 해주는 색인 정도의 실용적 목적입니다. 필수는 아니며, Vault가 꽤 커진 뒤에 여유가 있으면 시도해볼 선택 사항입니다.

파일명 규칙

한글 파일명 사용 가능하며, 반드시 주제별 폴더(기획/, 개발/, private/ 등) 안에 넣고 관련 태그와 frontmatter를 채웁니다 (문서 메타데이터 섹션 참고):

docs/content/기획/[[문서명]].md   #스펙
docs/content/개발/개발프로세스.md  #체크리스트
docs/content/개발/[[기능명]]_구현프롬프트.md  #프롬프트

4. AI 작업 공통 체크리스트

작업 전 어느 시스템(Spec / ADR / Vault)에 해당하는지 먼저 판단한 뒤, 해당 섹션의 규칙을 따릅니다.

1. 기능/작업 관련 스펙은 docs/specs/에 LeanSpec 도구로만 생성·수정합니다 (수동 파일 생성 금지, frontmatter 수동 편집 금지). LeanSpec을 쓰지 않는 프로젝트라면 이 항목은 무시합니다.
2. 중요한 아키텍처/방향 결정은 docs/decisions/에 새 ADR 파일로 기록합니다 (기존 ADR 수정 금지, 새 파일로 대체).
3. 일반 기획/개발 문서는 docs/content/ 하위 주제별 폴더에 저장하고, frontmatter·태그·MOC 링크 규칙을 따릅니다. docs/ 최상위(Quartz 설정 위치)에는 절대 문서를 두지 않습니다.
4. 문서 하나에는 하나의 주제만 담습니다. 다른 문서에 이미 있는 내용은 [[문서명]] 링크로 참조합니다.
5. 각 섹션은 문맥 없이도 이해할 수 있게 쓰고, "위에서 언급했듯이" 같은 문서 내 위치에 의존하는 표현을 피합니다. 한 화면을 넘기는 문서에는 상단에 짧은 요약(TL;DR)을 둡니다.
6. 문서를 수정하기 전에 기존 구조와 관련 문서(백링크 대상)를 먼저 확인합니다. 수정 후에는 frontmatter의 updated 날짜를 갱신합니다.
7. 더 이상 유효하지 않은 Vault 문서는 삭제하지 말고 status: archived로 표시합니다. 내용이 바뀌었다면 옛 문서에 변경 사실과 새 문서 링크를 남깁니다.
8. 큰 구조 변경(폴더 재편, 다수 문서 이동 등)은 먼저 사용자에게 확인합니다.
9. 관련 없는 문서는 수정하지 않습니다.