JunkBox 문서 작성 규칙
1. 문서 목적
vault/docs/junkbox의 1순위 독자는 AI 코딩 에이전트임. AI가 시스템 구조와 업무 의도를 빠르고 정확하게 파악하도록 돕는 것이 목적임.- 2순위 독자는 시스템을 기술·업무 관점에서 파악하려는 사용자와 관리자임.
- 문서는 벡터 검색으로 일부 조각만 읽히는 경우가 많음. 한 조각만 읽어도 무엇에 대한 설명인지 알 수 있게 작성함.
2. 내용 원칙
2.1 현황과 의도만 작성
- 문서는 지금 동작하는 구조와 그렇게 만든 의도를 설명함.
- 변경 이력, 작업 경과, 과거 구조와의 비교는 작성하지 않음. 이력은 Git이 소유함.
기존에는,변경했음,제거했음,추가됨처럼 변화를 서술하는 표현을 쓰지 않고 현재 상태로 다시 씀.- 사용하지 않는 것을 나열하지 않음. AI가 잘못 추정하기 쉬운 경계만 한 줄로 명시함.
- 시작 시 호환 처리처럼 지금 실행되는 동작은 현재 동작으로 서술함.
- 특정 날짜·버전·작업 트리 상태처럼 곧 달라지는 사실은 적지 않음. 필요하면 확인할 위치를 안내함.
2.2 의도 설명
- 규칙에는 가능한 한 이유를 함께 적음. 이유가 있어야 AI가 문서에 없는 상황에서도 같은 방향으로 판단함.
- 업무 규칙은 구현 서술과 분리함. 앱이 왜 존재하고 무엇을 관리하는지는 앱 가이드의
업무 개요에 둠.
2.3 단일 소유
- 같은 사실은 한 문서에만 적고 다른 문서는 경로로 참조함.
- 앱·개발 포트·권한 코드·SQLite 파일·운영 서비스명 목록은
docs/junkbox/common/guide-jb-overview.md의 앱 표만 소유함. 다른 문서에 전체 목록을 반복하지 않음. - 공통 규칙을 앱 가이드에 다시 풀어 쓰지 않음. 앱 가이드는 그 앱에만 해당하는 내용과 공통 규칙의 예외를 적음.
- AI 작업 절차와 승인 규칙은
junkbox저장소의AGENTS.md와.agents/skills/가 소유함. Vault 문서에는 절차를 복제하지 않고 구조와 의도만 둠. - 계획·검토·조사 결과처럼 특정 시점의 문서는
docs/junkbox에 두지 않음.
3. 문체
- 종결은
~함,~임,~됨,~음같은 명사형 종결을 사용함. ~해요,~이에요같은 해요체는 쓰지 않음. 명사형 종결이 어색한 문서는 하십시오체(~합니다)를 문서 전체에 일관되게 사용함.- 한 문서 안에서 문체를 섞지 않음.
- 화면 문구나 메시지 원문을 인용할 때는 백틱으로 감싸고 원문 그대로 적음.
- 코드 식별자, 경로, 명령, 설정 키, 화면 라벨은 백틱으로 표기함.
4. 구조
4.1 폴더
| 폴더 | 내용 | 파일명 |
|---|---|---|
common/ | 전체 공통 구조·원칙·규칙 | guide-jb-*.md |
libs/ | 공통 라이브러리의 책임과 사용 규칙 | guide-lib-{라이브러리}.md |
apps/ | 앱별 업무 목적, 책임 경계, 데이터, API, 화면 | guide-apps-{앱}-api.md, guide-apps-{앱}-ui.md |
domain/ | 구현과 무관하게 유지되는 업무 지식과 용어 | guide-*, policy-*, terms-* |
- 화면이 없거나 규모가 작은 앱은
guide-apps-{앱}.md단일 문서로 둘 수 있음. - 새 문서를 추가하면 시스템 개요의 문서 체계 표를 함께 갱신함.
4.2 앱 가이드 표준 틀
- 앱 문서의 최상위(
##) 절은 아래 순서를 따름. 해당 없는 절은 생략하되 순서는 바꾸지 않고, 번호는 남은 절에 순서대로 붙임. 점검 스크립트가 절 이름과 순서를 검사함. - API 가이드와 단일 앱 가이드(
guide-apps-{앱}-api.md,guide-apps-{앱}.md):
| 순서 | 절 이름 | 내용 |
|---|---|---|
| 0 | 업무 개요(번호 없음) | 앱이 해결하는 문제, 핵심 개념과 용어, 주요 사용 흐름 |
| 1 | 역할과 책임 경계 | 소유하는 것과 소유하지 않는 것, 구현 제약 |
| 2 | 런타임과 배포 | 엔트리포인트, 포트, 환경 설정, 배포 정책, 로깅 |
| 3 | 인증과 권한 | 로그인·권한 코드·복귀·세션 흐름 |
| 4 | 데이터 | 테이블, 저장 규칙, 파일 구조, 스키마 적용 |
| 5 | 업무 규칙 | 앱 고유의 판정·계산·생성·수집 규칙 |
| 6 | API와 화면 진입 | 라우트, API 계약, 서버 앱 셸 |
| 7 | 연동 | 다른 앱·외부 시스템·공통 라이브러리 연결 |
| 8 | 화면 구조 | 서버가 직접 설명해야 하는 화면 구성(UI 가이드가 없는 경우) |
| 9 | 검증 | 테스트·점검 방법 |
| 10 | 관련 문서 | 참조 문서 경로 |
- UI 가이드(
guide-apps-{앱}-ui.md)의 최상위 절:역할과 실행(런타임·엔트리·페이지·프록시·로그인 복귀) →공통 UI 계약(공통 의존, 구현 원칙, 공통 컴포넌트 적용과 예외) →화면 구조(화면별 구조와 동작) →데이터 계약(API 응답 타입 소비) →검증→관련 문서. - 화면 구조와 동작은 UI 가이드가 소유하고 API 가이드는 서버가 제공하는 계약만 적음.
guide-apps-junkbox-app.md(네이티브 앱)는 별도 틀을 사용함.- 새 문서를 만들거나 기존 절을 옮길 때 이 틀을 따르고, 제목 번호를 바꾸면 그 번호를 참조하는 문서를 함께 고침.
4.3 제목과 불릿
- 벡터 검색은 제목 단위로 문서를 나누므로 화면·기능·테이블 단위로 제목을 나눔. 한 제목 아래 내용은 3,000자를 넘기지 않음.
- 불릿 하나에는 한 가지 사실만 적음. 300자를 넘으면 첫 문장을 주제로 두고 나머지를 하위 불릿으로 나눔.
- 제목 번호를 바꾸면 그 번호를 참조하는 다른 문서와
junkbox저장소의 지침·주석을 함께 확인함. - 목록·대응 관계·속성 비교는 표를 사용함.
5. 관리
- 문서를 수정한 뒤 벡터 캐시 동기화(
scripts/sync_dev_docs.py)는 사용자가 검토 후 실행함. vault/scripts/check_junkbox_docs.py로 문체, 이력 표현, 불릿 길이, 앱 목록 일치를 점검함.- 코드와 문서가 다르면 코드를 기준으로 문서를 고침. 문서에만 있는 계획은 구현된 것으로 취급하지 않음.