이 파일은 이 저장소에서 작업하는 에이전트를 위한 기본 진입점이다.
CLAUDE.md는 이 문서를 가리키는 얇은 진입점이며, 실제 규칙은 여기와 docs/harness/에만 둔다.
- 이 저장소의 하네스 문서는
docs/harness/만 신뢰한다. - machine-readable path/script/import guard 목록은
docs/harness/manifest.json을 canonical source로 둔다. - 기존
docs/spec-v1/,docs/issues-v1/,docs/en/, 루트README.md는 기본적으로 무시한다. - 사용자가 기존 문서를 직접 비교하거나 갱신하라고 요청한 경우에만 예외로 읽는다.
docs/harness/README.mddocs/harness/architecture-map.mddocs/harness/change-workflow.mddocs/harness/quality-gates.mddocs/harness/area-ownership.md- 필요하면
docs/harness/task-template.md
정확한 machine-checked 경로 목록과 required npm script, renderer import guard는 docs/harness/manifest.json을 기준으로 한다. 아래 목록은 사람이 읽기 위한 요약이다.
- 앱 부트스트랩:
src/main.tsx,src/App.tsx - 렌더러 핵심 화면:
src/components/ChatView.tsx,src/components/InputArea.tsx,src/components/chat/ChatMessagePane.tsx - 세션 상태:
src/store/sessions.ts,src/store/sessionStoreState.ts,src/store/sessionStoreMutators.ts - Claude 스트리밍:
src/hooks/useClaudeStream.ts,src/hooks/claudeStream/* - 메인 프로세스:
electron/main.ts - Preload 경계:
electron/preload.ts,electron/preload/claudeApi.ts,electron/preload/quickPanelApi.ts - Claude IPC:
electron/ipc/claude.ts,electron/ipc/claude/* - 파일/OS IPC:
electron/ipc/files.ts,electron/services/fileService.ts,src/hooks/useFileExplorer.ts,src/hooks/useChatOpenWith.ts,src/components/toolcalls/useHtmlPreviewController.ts - Git IPC/서비스:
electron/ipc/git.ts,electron/services/gitService.ts,electron/services/git/* - Quick Panel:
src/quick-panel/*,src/hooks/useAppDesktopEffects.ts,electron/ipc/quickPanel.ts,electron/preload/quickPanelApi.ts,electron/main/windowController.ts - 레거시 예약 작업 마이그레이션:
src/main.tsx,electron/persistence.ts,electron/ipc/storage.ts,electron/services/scheduledTaskScheduler.ts - 설정 데이터:
electron/ipc/settings.ts,electron/services/settingsDataService.ts,electron/services/settingsData/*
- 변경 요청을 기능 축과 사용자 동작 기준으로 분류한다. 사용자가 특정 화면만 지목해도 scope는 화면 파일이 아니라 그 동작을 공유하는 영역으로 본다.
docs/harness/area-ownership.md에서 해당 영역과 인접 경계를 확인하고, 같은 component/hook/store action/state shape를 소비하는 인접 surface를 먼저 찾는다.- 필요한 파일만 읽고 최소 경계 안에서 수정한다.
- 같은 요청 안에서 다음 명백한 구현/통합/검증 단계가 남아 있으면 사용자 확인을 기다리지 말고 이어서 진행한다.
- 구조나 흐름이 바뀌면
docs/harness/를 같이 수정한다. - 최소
npm run harness:check를 실행한다. - TypeScript를 건드렸다면
npm run typecheck또는npm run harness:check:strict까지 실행한다. - 결과를 사용자에게
변경 내용,검증,남은 리스크순으로 짧게 정리하고, 확인한 인접 surface 또는 의도적으로 제외한 surface가 있으면 이유를 함께 적는다.
- 기본값은
autonomous until blocked다. 사용자가 명시적으로 멈추거나 계획만 원한다고 하지 않는 한, 분석에서 멈추지 말고 구현과 검증까지 끝낸다. - 요청을 수행하는 데 필요한 세부조건이 일부 비어 있으면 먼저 합리적 가정을 세우고 진행한다.
- 작은 안정 경계 하나를 끝냈다고 바로 멈추지 않는다. 원래 요청의 완료조건이 아직 안 닫혔고 다음 단계가 명백하면 같은 흐름에서 계속 진행한다.
- 진행 중에는 짧게 상태를 공유하되, 매 단계마다 승인이나 확인을 요구하지 않는다.
- 아래 경우에는 멈추고 질문한다:
- 파괴적이거나 되돌리기 어려운 변경이 필요한 경우
- 현재 작업 트리의 사용자 변경과 직접 충돌하는 경우
- 서로 다른 제품 결정이 가능하고 어느 쪽이 맞는지 추론하기 어려운 경우
- 필요한 자격 증명, 외부 리소스, 환경 정보가 없어 검증이나 구현을 안전하게 끝낼 수 없는 경우
- 렌더러에서 Node/Electron API를 직접 호출하지 않는다.
window.claude또는window.quickPanel만 사용한다. - IPC 계약을 바꾸면 preload 타입과 렌더러 호출부를 같이 맞춘다.
- 세션/예약 작업의 persisted shape를 바꾸면 마이그레이션 영향부터 확인한다.
- 스트림, watcher, timer를 추가하면 해제 경로도 같은 변경에서 보장한다.
- 특정 화면만 수정하더라도 같은 사용자 동작을 공유하는 다른 진입점과 표시 surface를 확인하지 않으면 완료로 보지 않는다.
- 새 구조를 도입했으면 문서가 코드보다 뒤처지지 않게 같은 PR에서 갱신한다.