본문으로 건너뛰기

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업무 규칙앱 고유의 판정·계산·생성·수집 규칙
6API와 화면 진입라우트, 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로 문체, 이력 표현, 불릿 길이, 앱 목록 일치를 점검함.
  • 코드와 문서가 다르면 코드를 기준으로 문서를 고침. 문서에만 있는 계획은 구현된 것으로 취급하지 않음.