Skip to content

AGENTS.md

Latest commit

 

History

History
255 lines (190 loc) · 11.4 KB

AGENTS.md

File metadata and controls

255 lines (190 loc) · 11.4 KB
Raw

Study Builder Agent Handoff

이 문서는 새 에이전트가 현재 작업을 안전하게 이어가기 위한 저장소 수준 안내서다. 작업 시작 전 이 파일과 수정 대상 아래의 prototype/AGENTS.md를 모두 읽는다.

1. 현재 제품 방향

Study Builder는 로컬 우선 Electron 학습 애플리케이션이다.

  • 위키형 학습서: 문서 읽기·탐색·개인 편집이 중심이다. 학습 모드를 노출하지 않는다.
  • 실습형 학습서: 위키 내용과 로컬 Workspace, 코드 편집기, 제한된 터미널, AI 도움을 연결한다.
  • 모든 학습서는 같은 위키 View(헤더·목차·본문 셸)를 사용한다. 실습형 학습서만 학습 모드와 실습 진입을 추가하고, 읽기 중심 책에서는 이를 숨긴다.
  • 실제 파일, 저장 데이터, 실행 결과를 사용한다. 성공처럼 보이는 더미 동작을 만들지 않는다.
  • 사용자 파일과 Provider Secret은 Renderer에 직접 노출하지 않는다.

상세 제품 결정과 반응형 규칙은 다음 문서가 기준이다.

  • prototype/AGENTS.md
  • design.md
  • README.md
  • prototype/docs/course-authoring.md

2. 2026-07-31 현재 상태

브랜치는 main이며 마지막 확인 HEAD는 d7bcc2c였다. 이 값은 바뀔 수 있으므로 항상 git branch --show-current와 git log -8 --oneline으로 다시 확인한다.

작업 트리는 깨끗하지 않다. 기존 사용자 작업과 에이전트 작업이 함께 남아 있다. git status --short가 현재 상태의 유일한 기준이며, 문서에 적힌 파일 목록보다 우선한다.

현재 구현된 주요 범위:

  • Electron Main / Preload / React Renderer 보안 경계
  • 로컬 위키 CRUD와 재시작 복원
  • Spring Boot 16개 강의 문서와 계층 목차
  • 18개 실습 단위, 성공한 검증 결과 기반 진도
  • 최근 Workspace 복원과 안전한 파일 CRUD
  • Monaco 편집기, PTY 터미널, 승인된 Gradle 명령
  • OpenAI, Gemini, OpenAI-compatible, Codex Provider
  • AI Context 미리보기, Markdown 스트리밍, 취소, Diff 승인
  • Spring Initializr 수준의 시작 템플릿

최근 수정한 회귀:

  • 경제학과 Spring Boot 위키는 prototype/src/wiki/SpringWikiScreen.jsx의 공통 위키 View를 사용한다.
  • 내부 호환용 screen="legacy" 값은 남아 있지만 별도 구형 View를 렌더링하면 안 된다.
  • Spring Boot 책만 공통 위키 View에서 학습 모드 전환과 screen="practice"를 노출한다.
  • 홈의 책 열기 분기는 prototype/src/StudyBuilderApp.jsx에 있다.
  • 재시작 복원 분기는 prototype/electron/storage/app-repository.ts의 screenFor에 있다.
  • 경제학 기본 메타데이터는 prototype/electron/storage/seed-data.ts에 있다.

마지막 검증 결과:

  • npm run typecheck: 통과
  • npm run build:desktop: 통과
  • npm test: 37 files, 205 tests 통과
  • npm run test:e2e -- --workers=1 --retries=0: 51 tests 통과

위 결과는 당시 작업 트리 기준이다. 새 변경 후에는 다시 실행해야 한다.

3. 디자인 기준

기술 편의를 이유로 기존 화면을 전면 재설계하지 않는다.

경제학 위키의 승인 기준:

  • Figma file key: HdxjSbLGMouLWHXKd5K50G
  • Figma node: 70:2
  • 화면: 경제 뉴스를 읽기 위한 기초 경제학 / 03-2. 기준금리
  • 260px 목차, 780px 안팎의 읽기 본문, 56px 위키 헤더
  • 4개 장의 전체 목차, 목차 검색, 학습자·목표 푸터
  • 출처·질문·수정 기록 도구
  • 로컬 기준 캡처:
    • audit/01-default-reading-1440.png
    • audit-alignment/05-figma-default-after.png
    • audit/local-prototype/book-types/economics-wiki-only-1440.png

Spring 위키 시작 콘텐츠의 참고 노드는 Figma node 125:2다. 콘텐츠 구성은 책마다 달라도 위키 화면의 헤더·목차·본문 레이아웃과 상호작용은 경제학 기준 View와 동일하게 유지한다.

시각 변경 후에는 DOM assertion만 믿지 말고 실제 Electron 화면을 캡처한다. 1440px를 기본으로 확인하고 관련 변경이면 1280px와 1024px도 확인한다.

4. 강의와 템플릿의 Source of Truth

Spring 강의 원문:

prototype/resources/course-sources/spring-course/notion/
prototype/resources/course-sources/spring-course/course-manifest.json
prototype/resources/course-sources/spring-course/practice-manifest.json

Notion 원문:

  • 강의: https://app.notion.com/p/SpringBoot-3aa6e559a65080b8ace0f98e381cd264
  • 제품 피드백: https://app.notion.com/p/3ad6e559a650802984bde7a33d2645c5

앱은 실행 중 Notion을 읽지 않는다. 저장소의 Markdown은 2026-07-31에 가져온 스냅샷이다. 사용자가 동기화를 요청했을 때만 현재 Notion을 다시 가져오고, 가져온 뒤 문장을 학습서에 맞게 다듬되 실행 가능한 코드와 구조는 보존한다.

강의 원문 또는 manifest를 바꾼 뒤:

cd prototype
npm run build:course

다음 생성물은 직접 편집하지 않는다.

prototype/src/course/
prototype/electron/storage/spring-course-seed.ts
prototype/electron/terminal/course-approved-commands.ts
prototype/electron/storage/course-practice.ts
prototype/public/course-assets/

Spring 시작 템플릿 원본:

prototype/resources/template-sources/spring-boot-rest/

템플릿 원본을 바꾼 뒤:

cd prototype
npm run build:templates

prototype/resources/templates/spring-boot-rest.zip은 생성물이므로 직접 수정하지 않는다. 완성 답안은 prototype/resources/reference-sources/studymate-complete/에만 둔다.

루트의 spring-course.zip, study-builder-spring-course-patch.zip 등은 참고 입력물이다. 현재 작업 트리를 덮어쓰지 말고, 임시 디렉터리에 풀어 diff를 확인한 뒤 필요한 파일만 선택적으로 반영한다.

5. 작업 절차

작업 시작:

git status --short
git branch --show-current
git log -8 --oneline --decorate
cd prototype
npm ci

node_modules가 현재 lock과 일치하고 이미 설치돼 있다면 npm ci는 생략할 수 있다.

실제 Electron 개발 실행:

cd prototype
npm run dev:desktop

브라우저 npm run dev는 레이아웃 확인용 fallback이다. Workspace, PTY, Secret 저장, Electron IPC를 검증할 때는 반드시 dev:desktop 또는 Playwright Electron fixture를 쓴다.

수정 순서:

  1. 증상을 재현하고 기존 캡처·Figma·Notion 중 해당 기능의 기준을 확인한다.
  2. UI 이벤트부터 Renderer, Preload, IPC, Main 서비스, 저장소까지 실제 흐름을 추적한다.
  3. 기존 구현을 재사용하고 공통 경계의 원인을 한 번만 수정한다.
  4. 사용자 데이터 마이그레이션과 재시작 복원을 함께 검토한다.
  5. 가장 작은 관련 테스트를 먼저 실행한다.
  6. 실제 Electron에서 버튼을 클릭하고 화면 캡처를 확인한다.
  7. 전체 타입·테스트·빌드를 실행한다.

6. 검증 명령

빠른 검증:

cd prototype
npm run typecheck
npx vitest run path/to/related.test.ts
npx playwright test path/to/related.spec.ts --workers=1 --retries=0
git diff --check

최종 검증:

cd prototype
npm run build:course
npm run build:templates
npm run typecheck
npm test
npm run test:sites
npm run build:desktop
npm run test:e2e -- --workers=1 --retries=0

별도 lint script는 없다. 타입 검사, Vitest, Playwright, git diff --check를 사용한다. E2E 시각 테스트는 audit/의 PNG를 갱신할 수 있으므로 커밋 전 변경 내용을 확인한다.

6.1 캡처·영상 스모크 검증

  • 브라우저 레이아웃만 확인할 때는 Vite dev server를 0.0.0.0으로 실행하고 Playwright Chromium으로 접속한다. 기본 캡처 해상도는 1440x900 PNG다.
  • 영상은 Playwright recordVideo 또는 page/video 캡처를 사용해 실제 UI 흐름을 약 10~20초 녹화한다. 정지 화면을 영상 파일로 위장하거나 fake artifact를 만들지 않는다.
  • 먼저 prototype/capture-smoke.mjs와 prototype/package.json의 capture:smoke 스크립트를 확인하고 재사용한다. 브라우저 캡처의 기본 산출물은 artifacts/smoke-test.png와 artifacts/smoke-test.webm이다.
  • 캡처 전 해당 기능의 typecheck, 관련 테스트, build를 실행한다. 캡처 후 두 파일이 실제로 존재하고 0바이트가 아닌지 확인하며, PNG는 실제 해상도를 확인하고 WebM은 ffprobe 등으로 재생 가능한지 검증한다.
  • Electron Main/Preload/PTY/Workspace/Provider처럼 Electron 런타임이 필요한 기능은 브라우저 캡처를 성공 근거로 삼지 않는다. dev:desktop 또는 Playwright Electron fixture로 실제 Electron 앱을 실행하고 캡처한다.
  • DISPLAY가 없으면 먼저 xvfb-run 등 가능한 대안을 확인한다. 대안이 없거나 실행이 실패하면 실패 사실과 원인을 기록하고 캡처 산출물을 만들지 않는다.
  • 기능 단위 순서는 구현 → 관련 테스트 → 캡처/검증 → 독립 커밋으로 반복한다. 캡처가 필요한 기능은 캡처 검증이 끝나기 전에 완료 또는 커밋으로 보고하지 않는다.

관련 회귀 테스트:

  • 경제학/Spring 공통 위키 View: prototype/tests/e2e/unified-wiki-ui.spec.ts
  • 앱 탭 화면 종류: prototype/tests/unit/app-tabs.test.ts
  • 강의·실습 흐름: prototype/tests/e2e/learning-flow.spec.ts
  • 반응형/접근성 캡처: prototype/tests/e2e/visual-accessibility.spec.ts
  • 최근 Workspace: prototype/tests/e2e/recent-workspace.regression-012.spec.ts
  • AI Markdown/패널: prototype/tests/e2e/course-experience.regression-014.spec.ts

7. Git과 데이터 안전

  • 기존 미커밋 파일을 삭제, 초기화, checkout, reset하지 않는다.
  • git reset --hard, 강제 checkout, rebase, squash, force push를 사용하지 않는다.
  • git add . 대신 이번 변경 파일만 명시적으로 stage한다.
  • 기존 사용자 변경과 새 수정이 한 파일에 섞이면 diff hunk를 검토해 선택적으로 stage한다.
  • 요청 없이 원격에 push하지 않는다.
  • API Key, .env, 인증서, SSH 키, userData, Workspace 파일, 빌드 산출물을 커밋하지 않는다.
  • 커밋 전 git status, git diff, 관련 테스트, git diff --check를 확인한다.
  • 현재 dirty tree 전체를 한 커밋으로 묶지 않는다.

8. 구현 시 지켜야 할 경계

  • Renderer에 Node.js, Electron 객체, raw ipcRenderer, API Key를 노출하지 않는다.
  • 범용 IPC 채널 대신 명시적인 도메인 API와 Main 입력 검증을 사용한다.
  • Workspace 경로는 canonical root 안인지 확인하고 traversal과 symlink 탈출을 막는다.
  • 파일 삭제는 확인 후 OS 휴지통을 우선한다.
  • AI Context에 .env, 자격 증명, 키, 바이너리, 과대 파일을 자동 포함하지 않는다.
  • 터미널은 승인된 명령만 실행하며 창 종료·취소 시 자식 프로세스를 정리한다.
  • 화면 이동만으로 실습 완료나 진도를 올리지 않는다.
  • 저장 실패를 성공처럼 표시하지 않는다.
  • 기존 디자인을 유지하면서 로딩, 빈 상태, 실패, 취소, 저장되지 않은 변경 상태를 제공한다.

9. 완료 보고

최종 답변에는 다음을 사실대로 적는다.

  • 수정한 증상과 근본 원인
  • 주요 변경 파일
  • 실제 실행한 검증 명령과 통과/실패 수
  • 새 캡처 위치
  • 검증하지 못한 항목
  • 생성한 커밋 해시, 또는 커밋하지 않은 이유

검증하지 않은 내용을 성공했다고 표현하지 않는다.