위키

프로젝트 위키는 프로젝트를 설명하는 Markdown 페이지 폴더입니다. 각 부분이 무엇을 하는지, 왜 그렇게 동작하는지, 증거가 어디에 있는지를 설명합니다. 사람이 읽고, 에이전트가 유지 관리합니다. 새로운 소스, 질문, 또는 코드 변경이 있을 때마다 위키가 조금 더 완전하고 정확해져야 합니다.

이것은 'LLM 위키' 패턴을 따릅니다: 원시 소스를 보관하고, 이를 요약하고 연결하는 페이지를 작성하며, 전체를 탐색 가능하게 유지하기 위해 인덱스와 로그를 유지합니다.

저장소 규칙이 우선입니다

저장소에 이미 위키가 있다면, 아무것도 변경하기 전에 해당 스키마 또는 지침 파일(주로 wiki/README.md, wiki/AGENTS.md, 또는 wiki/schema.md)을 읽으세요. 그 파일의 레이아웃, 메타데이터, 링크 스타일, 및 명령어가 여기의 기본값보다 우선합니다. 저장소의 위키 스크립트가 있다면 그것을 사용하고, 스크립트가 생성하는 파일은 수동으로 편집하지 마세요.

구성 요소

구성 요소	설명	편집자
소스	이슈, PR, 기사, 노트, 녹취록 등 원자료의 사본	한 번 추가된 후 절대 변경되지 않음
페이지	주제에 대한 서면 설명, 소스와 코드 인용	사실이 변경될 때마다 업데이트
스키마	위키 규칙을 담은 하나의 파일: 레이아웃, 메타데이터, 규칙	의도적으로 변경됨
인덱스	각 페이지를 한 줄 요약과 함께 나열한 목록	재생성되거나 완전하게 유지됨
로그	위키 변경 사항의 날짜가 기록된 추가 전용 목록	작업당 하나의 항목

새로운 위키의 기본 레이아웃은 다음과 같습니다:

wiki/
├── README.md     # 위키가 무엇이고 어떻게 사용하는지
├── schema.md     # 규칙 (규칙이 기록된 유일한 장소)
├── index.md      # 모든 페이지, 각 페이지 한 줄씩
├── log.md        # 변경된 사항, 최신 항목이 가장 아래
├── pages/        # 주제 페이지
└── sources/      # 원자료, 추가된 후에는 변경되지 않음

작은 프로젝트는 여기서 멈출 수 있습니다. 페이지가 많아서 사람들이 원하는 것을 찾기 어려울 때만 하위 폴더를 추가하세요.

출처가 다를 때 누가 옳은가

스키마에 어떤 종류의 주장에 대해 어떤 출처가 우선하는지 기록하세요. 대부분의 소프트웨어 프로젝트의 경우:

오늘날 코드의 동작 방식: 코드와 그 테스트.
무엇이 결정되었고, 왜 그런지: 결정 레코드, 이슈, 또는 결정이 내려진 PR.
계획 중이거나 진행 중인 사항: 이슈 트래커 또는 로드맵.

페이지와 그 권위 출처가 일치하지 않으면 페이지를 수정하고, 이전 정보가 기억할 가치가 있다면 무엇이 변경되었는지 짧은 노트를 남기세요. 출처를 일치시키기 위해 편집하지 마세요.

페이지

페이지당 하나의 주제, 명확한 제목을 사용하세요. 거의 중복된 페이지를 추가하는 대신 기존 페이지를 업데이트하세요.
주장하는 내용을 인용하세요. 출처로 링크하거나 파일 이름을 명시하세요. 독자는 중요한 진술을 확인할 수 있어야 합니다.
상대 Markdown 링크를 사용하세요 ([파서](parser.md)), 위키가 이미 다른 스타일을 사용하고 있지 않다면.

프론트매터를 작게 유지하세요. 유용한 최소 예시:

---
title: 파서
summary: 입력 파일을 읽고 검증하는 방법.
sources: [sources/issue-42.md]
code: [src/parser.ts]
updated: 2026-01-31
---

사람이나 스크립트가 사용할 때만 필드를 추가하세요.

모든 페이지에 접근 가능해야 하며, 인덱스와 최소한 하나의 관련 페이지에서 도달할 수 있어야 합니다.

작업

새 위키 설정

이미 존재하는 문서와 누가 그것을 읽는지 확인하세요. 작동 중인 문서 사이트를 중복하지 마세요.
레이아웃과 스키마를 사용자에게 제안하고, 페이지를 작성하기 전에 합의하세요.
README.md, schema.md, index.md, 및 log.md를 생성하세요.
프로젝트의 가장 중요한 부분에 대한 몇 페이지를 작성한 후 멈추고, 나머지를 채우기 전에 사용자와 확인하세요.
저장소의 에이전트 지침(AGENTS.md, CLAUDE.md)이 스키마를 가리키도록 하고, 규칙을 그 파일에 복사하지 마세요.

소스 추가

원자료를 sources/ 아래에 저장하고, 출처와 날짜를 기록하세요.
그것을 모두 읽으세요.
영향을 받는 기존 페이지를 모두 찾아 업데이트하세요. 해당 주제에 대한 페이지가 없을 때만 새 페이지를 만드세요.
현재 페이지와 모순되는 내용이 있으면 기록하고, 권위 규칙을 사용하여 해결하세요.
인덱스를 업데이트하고 로그 항목을 추가하세요.

어떤 페이지도 업데이트하지 않고 소스를 저장하는 것은 완료된 것이 아닙니다. 페이지가 사람들이 읽는 것입니다.

질문에 답변

인덱스에서 시작한 다음, 페이지 제목과 텍스트를 검색하세요.
관련 페이지를 읽고, 중요한 주장을 해당 출처 또는 코드와 비교하여 확인하세요.
사용한 페이지와 증거에 대한 링크와 함께 답변하세요. 의견이 일치하지 않거나 위키에 답변이 없는 부분을 언급하세요.
답변이 새롭고 다시 질문될 가능성이 높다면, 위키에 추가할 것을 제안하세요.

코드 변경 후 업데이트

변경 사항이 어떤 작업 방식을 변경하는 경우:

변경 사항이 영향을 준 파일, 함수 및 용어에 대해 위키를 검색하세요.
코드 변경과 동일한 PR에서 영향을 받는 모든 페이지를 업데이트하세요.
제목이나 요약이 변경된 경우 인덱스를 업데이트하고 로그 항목을 추가하세요.

위키 상태 확인

다음 사항을 확인하세요:

끊어진 링크 및 더 이상 존재하지 않는 코드 경로;
들어오는 링크가 없는 페이지;
동일한 주제에 대한 중복 페이지;
어떤 페이지도 인용하지 않는 소스;
서로 또는 코드와 일치하지 않는 페이지;
페이지가 누락되었거나 삭제된 페이지를 나열하는 인덱스.

링크 및 인덱스와 같은 기계적 문제는 직접 수정하세요. 페이지 병합 또는 어떤 주장이 옳은지 결정과 같은 판단이 필요한 사항은 사용자에게 보고하세요.

로그 항목

작업당 하나의 항목을 log.md 끝에 추가하세요:

## 2026-01-31 14:05 UTC: 수집 | 이슈 42, 빈 입력 줄

이슈를 소스로 추가하고 파서 페이지의 유효성 검사 섹션을 업데이트했습니다.

항상 시간과 시간대를 포함하여 같은 날의 항목이 순서를 유지하도록 하세요.

하지 말아야 할 것

소스를 추가한 후 편집하지 마세요.
허락 없이 위키의 큰 부분을 재구성하거나 이름을 바꾸지 마세요.
페이지가 오래되었다고 삭제하지 마세요. 오래되었다고 표시하고 대체한 내용에 링크하세요.
여러 곳에 동일한 규칙을 작성하지 마세요. 스키마가 유일한 사본입니다.
위키가 그것이 설명하는 코드보다 더 권위 있다고 취급하지 마세요.
사용자의 승인 없이 외부 시스템(Confluence, Notion, 이슈 트래커)에 기록하지 마세요.

lggarrison/agent-skills

agent-skills란 무엇인가요?

즐겨 사용하는 AI에게 물어보기

문서

위키