docs: architecture/tech-stack/conventions 전면 재작성 + Wiki 동기화

.agents/references/conventions.md

@@ -4,20 +4,37 @@
 
 ## 네이밍
 
+### Python (서버)
+
 | 대상 | 규칙 | 예시 |
 |------|------|------|
-| 변수/함수 | camelCase | `getUserData()` |
-| 클래스 | PascalCase | `UserService` |
-| 상수 | UPPER_SNAKE_CASE | `MAX_RETRY_COUNT` |
-| 파일명 | kebab-case | `user-service.js` |
-| CSS 클래스 | kebab-case | `.nav-header` |
+| 변수/함수 | snake_case | `write_pending_approval()` |
+| 클래스 | PascalCase | `GravityBot`, `WSHub`, `TokenManager` |
+| 상수 | UPPER_SNAKE_CASE | `MAX_MSG_SIZE`, `HEARTBEAT_INTERVAL` |
+| 파일명 | snake_case | `hub.py`, `ws_client.py` |
+| 로거명 | 모듈명 | `logging.getLogger("hub")` |
+
+### TypeScript (Extension)
+
+| 대상 | 규칙 | 예시 |
+|------|------|------|
+| 변수/함수 | camelCase | `writePendingApproval()`, `setupMonitor()` |
+| 클래스 | PascalCase | `WSBridgeClient` |
+| 인터페이스 | PascalCase | `BridgeContext`, `WSPendingData` |
+| 상수 | UPPER_SNAKE_CASE | `MAX_QUEUE_SIZE`, `AUTH_TIMEOUT` |
+| 파일명 | kebab-case | `ws-client.ts`, `step-probe.ts` |
+| export 함수 | camelCase | `initStepProbe()`, `generateApprovalObserverScript()` |
 
 ## 코드 스타일
 
-- 들여쓰기: (2 spaces / 4 spaces / tab)
-- 세미콜론: (사용 / 미사용)
-- 따옴표: (single / double)
-- 줄바꿈: LF (Unix style)
+| 항목 | Python | TypeScript |
+|------|--------|-----------|
+| 들여쓰기 | 4 spaces | 4 spaces |
+| 따옴표 | 쌍따옴표 `"` (f-string 포함) | 작은따옴표 `'` |
+| 세미콜론 | N/A | 사용 |
+| 줄바꿈 | LF (Unix) | CRLF (Windows, git 자동 변환) |
+| 최대 줄 길이 | 120자 권장 | 120자 권장 |
+| 타입 힌트 | 적극 사용 (`-> list[str]`) | strict (`BridgeContext` 인터페이스) |
 
 ## 커밋 메시지
 
@@ -25,21 +42,50 @@
 <type>(<scope>): <description>
 
 type: feat|fix|refactor|test|docs|chore|ci|infra
-scope: (선택)
+scope: server|extension|hub|bot|gateway|bridge (선택)
 ```
 
 **예시:**
-- `feat(server): add WebSocket reconnection logic`
-- `fix(frontend): resolve button overlap on mobile`
-- `docs: update API documentation`
+- `feat(hub): WebSocket Hub 구현 + JWT 인증`
+- `refactor(extension): 모듈 분리 (step-probe, observer-script)`
+- `fix(bot): auto-approve 세션 간 초기화`
+- `docs: architecture.md 전면 재작성`
+
+관련 Vikunja 태스크가 있으면: `feat(hub): WS Hub 구현 #task-395`
 
 ## 주석
 
 - 한국어/영어 혼용 가능
 - TODO 주석: `// TODO: 설명` 형식
+- 섹션 구분: `// ─── Section Name ───` (TypeScript), `# ─── Section ───` (Python)
 - 복잡한 로직에는 반드시 WHY(왜) 주석 추가
+- 함수 docstring: Python은 `"""..."""`, TypeScript는 `/** ... */`
+
+## 모듈 분리 패턴
+
+Extension 모듈 분리 시 사용하는 패턴:
+
+| 패턴 | 용도 | 예시 |
+|------|------|------|
+| **순수 함수 추출** | 외부 상태 참조 없는 함수 | `step-utils.ts` |
+| **독립 스크립트** | 문자열 반환 함수 | `observer-script.ts` |
+| **Context 패턴** | 공유 상태가 많은 함수 그룹 | `step-probe.ts` (BridgeContext) |
+| **클래스 추출** | 자체 상태 + 메서드 | `ws-client.ts` (WSBridgeClient) |
 
 ## 테스트
 
-- 테스트 파일 위치: (예: `__tests__/` 또는 `*.test.js`)
-- 테스트 네이밍: `should [expected behavior] when [condition]`
+| 항목 | 위치 | 도구 |
+|------|------|------|
+| Python 구문 검사 | `tests/test_syntax.py` | `ast.parse` |
+| WS Hub 연결 | `tests/test_ws_hub.py` | `websockets` |
+| TypeScript 컴파일 | `npx tsc --noEmit` | TypeScript compiler |
+| E2E | 수동 (Discord 버튼 클릭) | — |
+
+## 로깅
+
+| 측 | 방식 | 포맷 |
+|----|------|------|
+| Python | `logging.getLogger(name)` | `YYYY-MM-DD HH:MM:SS [name] LEVEL: message` |
+| Extension | `logToFile(msg)` → bridge/log/ | `[HH:MM:SS] message` + `[WS]` prefix |
+| Hub | `[HUB]` prefix | `[HUB] Auth OK: {conn_id} project={project}` |
+| Gateway | `[GATEWAY]` prefix | `[GATEWAY] HTTP API started on {host}:{port}` |