ai-code-app/docs

Docs Guide

프로젝트 문서는 작업일지, 기능 문서, 컴포넌트 문서를 기본 축으로 운영합니다. 현재 메인 앱 Docs 화면은 docs/**/*.md를 동적으로 수집해 폴더별로 노출합니다.

0. 임시 로컬 모드

• 현재 저장소는 당분간 로컬 전용으로 운영합니다.
• 문서 정리나 Codex 작업 시 Git 원격 동기화, 브랜치 운영, 자동 merge 흐름은 기본 전제로 사용하지 않습니다.
• Codex Live, 일반 채팅, 작업메모 반영 요청은 현재 프로젝트 루트의 로컬 main 작업본을 바로 수정하는 방식으로 처리합니다.
• Git 관련 작업은 사용자가 명시적으로 요청할 때만 수행합니다.

1. 작업일지

• 위치: docs/worklogs
• 규칙: 날짜별 1개 Markdown 파일 작성
• 파일명 예시: 2026-03-31.md
• 템플릿: docs/templates/worklog-template.md
• 권장 기록 범위: 구현 내용, 구조 변경, 빌드/배포 이슈, Git 작업 내역
• 최근 작업일지는 날짜별로 계속 누적 기록
• 화면 캡처는 docs/assets/worklogs/YYYY-MM-DD/ 아래에 저장하고 작업일지에서 상대 경로로 연결
• 캡처는 전체 화면보다 작업한 컴포넌트 영역 단위 이미지를 우선 사용
• 메뉴/기능 증적이 필요하면 capture:menu, capture:feature 스크립트로 화면 단위 캡처를 함께 남김
• 화면 캡처를 남기지 못한 날에도 ## 화면 캡처 섹션은 유지하고, 미첨부 사유를 한 줄로 기록
• 문서 최신화 작업을 수행한 날에는 어떤 문서를 왜 수정했는지 함께 기록

권장 항목:

• 오늘 작업한 내용
• 이슈 및 해결 과정
• 결정 사항
• 상세 작업 내역

2. 기능 문서

• 위치: docs/features
• 규칙: 기능 단위로 Markdown 파일 작성
• 파일명 예시: auth.md, dashboard.md
• 템플릿: docs/templates/feature-template.md
• 권장 기록 범위: 기능 목적, 화면 흐름, API/상태, 테스트 포인트
• docs/features/*.md를 추가하거나 수정하면 앱 Docs / 기능문서 메뉴에 반영됨
• src/features/**/*.md는 프로젝트 내부 전용 설명 문서용이며 메인 Docs 메뉴의 기본 수집 대상은 아님

권장 항목:

• 기능 목적
• 주요 화면/흐름
• 데이터 구조 및 API
• 예외 처리
• 테스트 포인트

3. 컴포넌트 문서

• 위치: docs/components
• 규칙: 컴포넌트별 1개 Markdown 파일 작성
• 파일명 예시: status-badge.md, user-card.md
• 대표 샘플: 각 컴포넌트의 samples/Sample.tsx
• 확장 샘플: samples/*.tsx

권장 항목:

• 목적
• 폴더 구조
• UI props
• plugin input/output 규칙
• plugin 합성 규칙
• Sample 활용 예시

현재 기준 주요 컴포넌트 구조:

src/components
├─ markdownPreview
├─ navigation
├─ previewer
├─ search
├─ status-badge
└─ window

공통 플러그인 타입과 유틸은 src/types/component-plugin.ts 에서 관리합니다.

샘플 운영 규칙:

• samples/Sample.tsx는 해당 컴포넌트의 가장 기본형만 표현
• plugin/feature 예시는 samples/*.tsx로 분리
• 샘플 목록에서는 같은 컴포넌트 기준으로 묶고 base -> plugin -> feature 순서로 정렬

4. 샘플/위젯 레이아웃

• 컴포넌트 샘플 레이아웃: 좌측 컴포넌트 목록 + 우측 상세 카드
• 상세 카드는 컴포넌트 하나당 1개
• 카드 내부는 Base Sample 아래에 Plugin Samples, Feature Samples를 순차적으로 배치
• 위젯 샘플은 widgets/**/samples/*.tsx 기준으로 별도 수집
• 실제 샘플 엔트리 로딩은 src/app/manifests/samples.manifest.ts, src/samples/registry.ts를 기준으로 동작

5. 프로젝트 종속 레이아웃

• 위치: src/features/layout
• 대상: 현재 프로젝트 화면에서만 사용하는 레이아웃
• 예시: 컴포넌트 샘플 목록, 위젯 샘플 목록, Docs markdown preview, Plan 게시판

프로젝트 종속 기능 규칙:

• 현재 프로젝트에서만 의미 있는 화면/기능은 src/features 아래에 둠
• 예: Plan 게시판, 대시보드 feature 샘플, 앱 전용 레이아웃
• 공통 컴포넌트/위젯으로 재사용 가능한 항목은 src/components, src/widgets에 유지

메인 화면 분리 규칙:

• 위치: src/app/main
• 구성: MainView, MainHeader, MainSidebar, MainContent
• 목적: 상단 메뉴, 사이드바, 본문, 검색/문서/Plan 흐름을 앱 레벨에서 분리

6. Markdown Preview

• 공통 markdown preview는 src/components/markdownPreview 아래에서 관리
• basePath를 받아 특정 폴더 아래 markdown 문서를 재사용 가능하게 렌더링
• docs 문서 영역은 좌측 폴더/문서 트리 + 우측 markdown 카드 목록 구조 사용
• 문서 수집 매니페스트는 src/app/manifests/docs.manifest.ts에서 관리
• docs/features, docs/components, docs/worklogs, docs/templates는 폴더 단위로 자동 분류됨
• docs/worklogs는 최신 날짜가 먼저 보이도록 역순 정렬

7. 대시보드 위젯/데이터

• 대시보드 카드 위젯은 src/widgets/dashboard-report-card
• 위젯 샘플과 프로젝트 종속 샘플은 분리
• 재사용 가능한 샘플 데이터는 src/data 아래에서 관리
• 프로젝트 전용 대시보드 샘플은 src/features/dashboard에 둠

8. 배포 메모

• Nexus publish 대상 registry는 package.json의 publishConfig.registry
• alpha 버전 배포는 npm publish --tag alpha
• Nexus 인증은 ~/.npmrc의 username / _password(base64) / email 방식으로 확인

9. etc 운영 기준

• 부가 서버/DB/타언어 프로젝트는 etc 아래에서 분리 관리
• 서버 예시: etc/servers/work-server
• DB 예시: etc/db/work-db
• etc 내부 비밀값과 생성물은 커밋 제외
  • .env
  • node_modules
  • dist
  • *.log

10. Plan 기능 문서 메모

• Plan 기능은 src/features/planBoard에서 관리
• 현재 앱에는 목록/상세 보드, release 검수, 차트, 스케줄 화면이 함께 포함됨
• 기본 상태는 등록, 작업중, 작업완료, 릴리즈완료, 완료
• 자동화 진행은 workerStatus로 별도 관리하며 브랜치 준비, 자동 작업, release/main 반영 상태를 표현
• 작업시작 이후에는 원본 요청(작업 ID, 원본 메모`)을 수정하지 않고 조치 이력으로 누적 기록
• 권한 토큰이 없으면 조회 중심으로 동작하며 민감 메모와 소스 작업 일부는 제한 또는 마스킹
• 관련 기능 문서는 docs/features/plan-board-review.md, plan-automation.md, plan-schedule.md, plan-usage.md 참고