|
1 | 1 | # CodeSyncer CLI |
2 | 2 |
|
3 | | -> AI 코딩이 멍청해? 똑똑하게 만들어줌 - 영구 컨텍스트, 추론 통제, 실시간 아키텍처 동기화 for Claude Code |
| 3 | +> **Claude는 세션이 끝나면 모든 것을 잊습니다. CodeSyncer가 기억하게 해줍니다.** |
4 | 4 |
|
5 | 5 | [](https://www.npmjs.com/package/codesyncer) |
6 | 6 | [](./LICENSE) |
|
11 | 11 |
|
12 | 12 | --- |
13 | 13 |
|
14 | | -## 🎬 데모 |
| 14 | +## ⚡ 문제 → 해결 |
| 15 | + |
| 16 | +| 문제 | CodeSyncer 없이 | CodeSyncer 사용 시 | |
| 17 | +|------|----------------|-------------------| |
| 18 | +| **맥락 손실** | 매 세션 = 처음부터 다시 | 코드 태그 = 영구 기억 | |
| 19 | +| **결정 망각** | "왜 JWT 썼더라?" → 🤷 | `@codesyncer-decision` → 즉시 확인 | |
| 20 | +| **위험한 추론** | AI가 가격, 엔드포인트, 인증 추측 | 중요 키워드 자동 일시정지 | |
| 21 | +| **기록 없음** | AI의 추론 이유 없음 | `codesyncer watch`가 모든 것 포착 | |
15 | 22 |
|
16 | | - |
| 23 | +**결과**: 현재 프롬프트만 아는 AI가 아닌, 프로젝트를 진짜로 학습하는 AI |
17 | 24 |
|
18 | 25 | --- |
19 | 26 |
|
20 | | -## 🤔 문제 상황 |
| 27 | +## 🎬 데모 |
| 28 | + |
| 29 | + |
21 | 30 |
|
22 | | -실제 프로젝트에서 AI 쓰면 이런 문제 생깁니다: |
| 31 | +--- |
23 | 32 |
|
24 | | -**1. 세션마다 컨텍스트 날아감** 😫 |
25 | | -- 새 AI 세션 = 처음부터 다시 설명 |
26 | | -- 같은 아키텍처 설명 반복 |
27 | | -- "API 엔드포인트가 뭐였지?" "인증은 어떻게 하지?" - 매번. 물어봄. |
| 33 | +## 🧠 작동 원리 |
28 | 34 |
|
29 | | -**2. 멀티레포 혼돈** 🤯 |
30 | | -``` |
31 | | -내-프로젝트/ |
32 | | -├── api-server/ (백엔드) |
33 | | -├── web-client/ (프론트엔드) |
34 | | -└── mobile-app/ (모바일) |
| 35 | +**핵심 인사이트**: AI는 코드를 읽습니다. 그러니 맥락을 코드 안에 넣으세요. |
| 36 | + |
| 37 | +```mermaid |
| 38 | +flowchart LR |
| 39 | + A[🧑💻 Claude와 코딩] --> B{결정 내림?} |
| 40 | + B -->|예| C[@codesyncer-decision 태그 추가] |
| 41 | + B -->|아니오| D{추론 했음?} |
| 42 | + D -->|예| E[@codesyncer-inference 태그 추가] |
| 43 | + D -->|아니오| F[계속 코딩] |
| 44 | + C --> G[📝 코드에 영구 저장] |
| 45 | + E --> G |
| 46 | + G --> H[🔄 다음 세션] |
| 47 | + H --> I[Claude가 코드 읽음] |
| 48 | + I --> J[✅ 맥락 복구 완료!] |
35 | 49 | ``` |
36 | | -- AI는 한 번에 한 레포만 봄 |
37 | | -- 다른 레포의 컨텍스트 부족 → 부분적인 코드만 생성 |
38 | | -- "로그인 추가해줘"는 백엔드 API + 프론트 UI 둘 다 필요한데 AI는 모름 |
39 | 50 |
|
40 | | -**3. AI가 위험한 추론을 함** ⚠️ |
41 | | -- "타임아웃 30초로 설정했어요" - 어? 5초여야 하는데! |
42 | | -- "/api/v1/... 사용했습니다" - 잘못된 엔드포인트! |
43 | | -- 비즈니스 로직, 보안 설정, 가격 정책을 마음대로 추론 |
| 51 | +```typescript |
| 52 | +// @codesyncer-decision: [2024-01-15] JWT 선택 (세션 관리가 더 간단함) |
| 53 | +// @codesyncer-inference: 페이지 크기 20 (일반적인 UX 패턴) |
| 54 | +// @codesyncer-rule: httpOnly 쿠키 사용 (XSS 방지) |
| 55 | +const authConfig = { /* ... */ }; |
| 56 | +``` |
44 | 57 |
|
45 | | -**결과**: 설명하고 고치는 시간이 실제 코딩 시간보다 더 김 |
| 58 | +다음 세션? Claude가 코드를 읽으면 **자동으로 모든 맥락이 복구됩니다**. |
46 | 59 |
|
47 | 60 | --- |
48 | 61 |
|
49 | | -## ✨ 해결 방법 |
| 62 | +## 🔥 Watch 모드: 맥락을 절대 놓치지 마세요 |
50 | 63 |
|
51 | | -CodeSyncer는 AI에게 **전체 그림**을 제공합니다: |
| 64 | +**문제**: Claude가 코딩하면서 태그 추가를 잊을 수 있습니다. |
52 | 65 |
|
53 | | -1. **📝 코드 주석** - 모든 결정과 맥락을 코드에 직접 기록 |
54 | | -2. **🗂️ 마스터 문서** - 레포 간 이동과 전체 규칙 관리 |
55 | | -3. **📋 레포별 문서** - 각 레포만의 특별한 가이드라인 |
56 | | -4. **🎯 키워드 시스템** - 중요한 결정(결제, 인증 등)에서 자동 일시정지 |
| 66 | +**해결**: `codesyncer watch`로 태그 없는 변경을 잡아내세요. |
57 | 67 |
|
58 | | -**결과**: 복잡한 멀티레포 프로젝트에서도 **정확도 높은** AI 코딩 🎯 |
59 | | - |
60 | | ---- |
| 68 | +```bash |
| 69 | +codesyncer watch |
| 70 | +``` |
61 | 71 |
|
62 | | -## 🎯 CodeSyncer란? |
| 72 | +``` |
| 73 | +[14:32:10] 📝 변경됨: src/utils/api.ts |
| 74 | + └── ⚠️ 태그 없음! |
| 75 | + 💡 힌트: 추론하면 @codesyncer-inference 추가 |
63 | 76 |
|
64 | | -CodeSyncer는 AI 코딩 어시스턴트(Claude Code 등)가 멀티 레포지토리 워크스페이스에 지능형 협업 시스템을 구축할 수 있도록 **프레임워크와 규칙**을 제공합니다. |
| 77 | +[14:33:22] 📝 변경됨: src/auth/login.ts |
| 78 | + └── 🎯 발견: @codesyncer-decision |
| 79 | + "SWR 대신 React Query 사용" |
| 80 | + └── ✅ DECISIONS.md에 추가됨 |
| 81 | +``` |
65 | 82 |
|
66 | | -**작동 방식:** |
67 | | -1. **사용자가** CodeSyncer CLI 설치 |
68 | | -2. **사용자가** AI 어시스턴트 실행 (Claude Code, Cursor 등) |
69 | | -3. **사용자가** `codesyncer init` 실행 |
70 | | -4. **AI가** 프로젝트를 분석하고 CodeSyncer 구조에 따라 문서 생성 |
| 83 | +**왜 중요한가**: 모든 코드 변경은 맥락을 기록할 기회입니다. Watch 모드가 놓치는 것 없이 잡아냅니다. |
71 | 84 |
|
72 | | -CodeSyncer는 문서가 **어디에, 어떻게** 만들어져야 하는지 정의합니다. AI 어시스턴트는 실제 코드를 분석하여 **무엇을** 작성할지 결정합니다. |
| 85 | +--- |
73 | 86 |
|
74 | | -### 주요 기능 |
| 87 | +## ✨ 전체 기능 목록 |
75 | 88 |
|
76 | | -- 🤖 **AI 도구 독립적**: Claude Code, Cursor, GitHub Copilot 등 모두 지원 |
77 | | -- 📁 **단일 & 멀티 레포 지원**: 개별 레포지토리 또는 전체 워크스페이스 모두 지원 |
78 | | -- 📦 **모노레포 지원**: Turborepo, pnpm, Nx, Lerna, npm/yarn workspaces 자동 감지 |
79 | | -- 🔄 **Watch 모드**: 실시간 파일 모니터링 및 태그 자동 동기화 |
80 | | -- ✅ **Validate 명령어**: 설정 검사 및 수정 제안 (v2.7.0 신규) |
81 | | -- 🏷️ **주석 태그 시스템**: `@codesyncer-*` 태그로 결정과 추론을 영구 기록 |
82 | | -- 🤝 **자동 의논 시스템**: 중요한 결정(결제, 보안 등)에서 자동으로 일시 정지 |
83 | | -- 🌐 **다국어 지원**: 한글/영문 완벽 지원 |
84 | | -- ⚡ **빠른 설치**: 한 번의 명령으로 전체 워크스페이스 설정 |
85 | | -- 🔒 **보안 강화**: 경로 탐색 공격 방지 및 입력 검증 (v2.7.0) |
| 89 | +| 기능 | 설명 | |
| 90 | +|------|------| |
| 91 | +| 🏷️ **태그 시스템** | `@codesyncer-decision`, `@codesyncer-inference`, `@codesyncer-rule` - 코드에 영구 맥락 | |
| 92 | +| 🔄 **Watch 모드** | 실시간 모니터링, 태그 없는 변경 경고, DECISIONS.md 자동 동기화 | |
| 93 | +| ✅ **Validate** | 태그 커버리지 확인, 누락된 문서 찾기, 수정 제안 | |
| 94 | +| 🤝 **자동 일시정지** | 결제/보안/인증 키워드 감지 → 코딩 전 확인 | |
| 95 | +| 📦 **모노레포** | Turborepo, pnpm, Nx, Lerna, npm/yarn workspaces 자동 감지 | |
| 96 | +| 🌐 **다국어** | 한글/영문 완벽 지원 | |
| 97 | +| 🔒 **보안** | 경로 탐색 방지 및 입력 검증 | |
86 | 98 |
|
87 | 99 | --- |
88 | 100 |
|
89 | | -## ⚠️ 사전 요구사항 |
90 | | - |
91 | | -**CodeSyncer는 AI 코딩 어시스턴트가 활성화되어 있어야 합니다.** |
92 | | - |
93 | | -현재 지원: |
| 101 | +## 🔄 전체 워크플로우 |
| 102 | + |
| 103 | +``` |
| 104 | +┌─────────────────────────────────────────────────────────────┐ |
| 105 | +│ 1. 설정 (최초 1회) │ |
| 106 | +│ $ npm install -g codesyncer │ |
| 107 | +│ $ codesyncer init │ |
| 108 | +│ → CLAUDE.md, SETUP_GUIDE.md 생성 │ |
| 109 | +└─────────────────────────────────────────────────────────────┘ |
| 110 | + ↓ |
| 111 | +┌─────────────────────────────────────────────────────────────┐ |
| 112 | +│ 2. AI 학습시키기 (세션마다 1회) │ |
| 113 | +│ Claude Code 열고 말하기: │ |
| 114 | +│ "CLAUDE.md 읽어줘" │ |
| 115 | +│ → Claude가 태그 시스템 학습 │ |
| 116 | +└─────────────────────────────────────────────────────────────┘ |
| 117 | + ↓ |
| 118 | +┌─────────────────────────────────────────────────────────────┐ |
| 119 | +│ 3. 코딩 (watch 모드 실행 상태로) │ |
| 120 | +│ $ codesyncer watch ← 백그라운드 실행 │ |
| 121 | +│ Claude와 평소처럼 코딩 │ |
| 122 | +│ → Claude가 @codesyncer-* 태그 자동 추가 │ |
| 123 | +│ → Watch 모드가 태그 누락 시 알림 │ |
| 124 | +└─────────────────────────────────────────────────────────────┘ |
| 125 | + ↓ |
| 126 | +┌─────────────────────────────────────────────────────────────┐ |
| 127 | +│ 4. 다음 세션 │ |
| 128 | +│ Claude가 코드 읽음 → 태그 확인 │ |
| 129 | +│ → 맥락 자동 복구 완료! │ |
| 130 | +└─────────────────────────────────────────────────────────────┘ |
| 131 | +``` |
| 132 | + |
| 133 | +**지원 AI 도구:** |
94 | 134 | - ✅ **Claude Code** (권장) |
95 | | -- 🚧 Cursor (곧 지원 예정) |
96 | | -- 🚧 GitHub Copilot (곧 지원 예정) |
97 | | -- 🚧 Continue.dev (곧 지원 예정) |
98 | | - |
99 | | -**중요**: CodeSyncer를 사용하기 전에 AI 코딩 어시스턴트를 **실행하고 활성화**해주세요. AI가 프로젝트를 분석하고 정확한 문서를 생성하는 데 도움을 줍니다. |
| 135 | +- 🚧 Cursor, GitHub Copilot, Continue.dev (곧 지원 예정) |
100 | 136 |
|
101 | 137 | --- |
102 | 138 |
|
|
0 commit comments