wiki: Topic_Blog 신규 문서 일괄 추가 + ASTRA 성장 자산 동기화
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
This commit is contained in:
Antigravity Agent
@@ -0,0 +1,110 @@
|
||||
---
|
||||
id: coding-conventions-comment-philosophy
|
||||
title: "코딩 컨벤션과 주석 철학"
|
||||
category: "Software_Engineering"
|
||||
status: "draft"
|
||||
verification_status: "applied"
|
||||
canonical_id: ""
|
||||
aliases: ["코딩 스타일", "주석 철학", "why comment", "post-mortem comment", "naming", "graceful degradation", "코드 컨벤션"]
|
||||
duplicate_of: ""
|
||||
source_trust_level: "A"
|
||||
confidence_score: 0.93
|
||||
created_at: 2026-06-13
|
||||
updated_at: 2026-06-13
|
||||
review_reason: ""
|
||||
merge_history: []
|
||||
tags: ["conventions", "style", "comments", "readability", "connectai"]
|
||||
raw_sources: ["ConnectAI/src/core/lock.ts", "ConnectAI/src/retrieval/index.ts", "ConnectAI/src/features/company/dispatcher.ts", "ConnectAI/src/extension.ts"]
|
||||
applied_in: ["ConnectAI"]
|
||||
github_commit: ""
|
||||
---
|
||||
|
||||
# [[코딩 컨벤션과 주석 철학]]
|
||||
|
||||
## 🎯 한 줄 통찰 (One-line insight)
|
||||
ConnectAI 코드의 가장 큰 특징은 "**주석이 '무엇'이 아니라 '왜'와 '왜 다른 방법이 아니었는지'를 적고, 버그 사후기록(post-mortem)을 코드 옆에 남긴다**"는 점이며, 이것이 작은 LLM 이 *의도까지* 학습하게 하는 핵심 자료다 [S1][S3].
|
||||
|
||||
## 🧠 핵심 개념 (Core concepts)
|
||||
1. **Why 주석:** 코드가 '무엇을 하는지'는 코드로 읽고, 주석은 '왜 이렇게 했는지'·제약·트레이드오프를 적는다 [S1].
|
||||
2. **Post-mortem 주석:** 과거 버그의 원인과 수정 근거를 코드 옆에 남겨 같은 실수를 막는다 [S1].
|
||||
3. **모듈 헤더 docstring:** 각 파일 상단에 그 모듈의 책임·배경·다른 모듈과의 분업을 설명 [S1][S4].
|
||||
4. **결정 근거 주석:** "왜 순차인가", "왜 handlePrompt 를 안 쓰나" 같은 설계 결정을 인라인으로 [S3].
|
||||
5. **방어적 기본값/널 처리 + 의도 명시:** `??` vs `||`, `void` fire-and-forget, 의도적 빈 catch 를 주석으로 [S2][S4].
|
||||
|
||||
## 🧩 추출된 패턴 (Extracted patterns)
|
||||
- **named export 일관:** default export 를 배제하고 named export 만 — 자동완성·리네이밍 안전 [S4].
|
||||
- **단일 진입점 헬퍼:** 설정은 `getConfig()`, 경로는 path resolver 처럼 한 곳을 통해 — 파싱/coercion 중복 방지 [S4].
|
||||
- **`??` 로 의미 있는 0/'' 보존:** `brainFileLimit ?? 8` (0 이 유효), `req.timeoutMs ?? config.timeout` [S2].
|
||||
- **의도된 graceful degradation:** 부가 작업 실패를 `catch { /* should never break main flow */ }` 로 — 빈 catch 에 *반드시* 이유 주석 [S2].
|
||||
- **단계 로그(추적성):** 복잡 로직은 `fusionLog.push(...)` 처럼 단계별 기록을 남겨 디버깅 [S2].
|
||||
- **상수 중앙화:** 가중치/임계값/불용어를 설정 객체 한 곳에(`SCORING_CONFIG`) [S2].
|
||||
- **한국어 주석 + 영어 식별자:** 식별자·타입은 영어, 설명 주석은 한국어 — 팀 가독성 우선 [S1].
|
||||
|
||||
## 📖 세부 내용 (Details)
|
||||
### 주석이 의도를 가르친다 (이 위키의 핵심 가치)
|
||||
`lock.ts` 의 주석은 옛 구현이 왜 틀렸는지를 적는다: "`.then(...)` 은 매 호출마다 새 Promise instance 를 반환해서 사실상 항상 false — cleanup 이 안 됨." 이런 주석은 *코드만 봐서는 절대 알 수 없는* 함정을 전수한다. 작은 LLM 이 비슷한 코드를 쓸 때 같은 함정을 피하게 만드는 최고의 학습 신호다 [S1].
|
||||
|
||||
### "왜 다른 방법이 아니었나" 를 적는다
|
||||
`dispatcher.ts` 헤더는 "Why sequential?", "Why not use handlePrompt?" 를 명시한다. 대안을 검토하고 *기각한 이유* 까지 적어, 미래의 개발자(또는 LLM)가 같은 고민을 반복하지 않게 한다 [S3].
|
||||
|
||||
### 방어적이되 명시적
|
||||
```typescript
|
||||
const brainFileLimit = options.brainFileLimit ?? 8; // 0 이 의미 있음 → || 아님
|
||||
void ensureEmbeddingConfigured(context); // 비차단 의도를 void 로 명시
|
||||
try { extract(); } catch { /* memory extraction should never break the main flow */ }
|
||||
```
|
||||
빈 catch·fire-and-forget 같은 "위험해 보이는" 패턴에는 *왜 안전한지* 를 항상 주석으로 정당화한다 [S2][S4].
|
||||
|
||||
### 네이밍
|
||||
- 함수는 동사구(`buildContext`, `searchBrainFiles`, `parseModelPrefix`), boolean 은 `is*`/`should*`/`has*`(`isOperationalPath`, `shouldUseMultiAgentWorkflow`).
|
||||
- 내부 전용은 `_` 접두사(`_ensureBrainDir`, `_getBrainDir`).
|
||||
- 타입은 PascalCase 인터페이스(`RetrievalChunk`, `ConfidenceResult`), 상수는 UPPER_SNAKE(`PEER_OUTPUT_BUDGET`).
|
||||
|
||||
## ⚖️ 모순 및 업데이트 (Contradictions & updates)
|
||||
- **주석 과다 vs 적정:** "코드가 자명하면 주석 불필요" 라는 원칙과 충돌할 수 있다. ConnectAI 의 기준은 *비자명한 why/제약/함정만* 적는 것 — "다음 줄이 무엇을 하는지" 류의 노이즈 주석은 피한다.
|
||||
- **주석의 노후화:** 코드가 바뀌면 주석이 거짓이 될 위험. post-mortem 주석은 역사적 사실이라 비교적 안전하나, "현재 동작" 주석은 변경 시 함께 갱신해야 한다.
|
||||
|
||||
## 🛠️ 적용 사례 (Applied in summary)
|
||||
- `ConnectAI/src/core/lock.ts` — 버그 post-mortem 주석의 모범 [S1].
|
||||
- `ConnectAI/src/features/company/dispatcher.ts` — 결정 근거(왜 순차/왜 분리) 주석 [S3].
|
||||
- `ConnectAI/src/retrieval/index.ts` — 단계 로그, 상수 중앙화, `??` 보존 [S2].
|
||||
|
||||
## 💻 코드 패턴 (Code patterns)
|
||||
```typescript
|
||||
// 1) Post-mortem 주석 — 코드로 알 수 없는 함정 전수 (src/core/lock.ts)
|
||||
// 옛 구현은 `this.locks.get(id) === prev.then(() => next)` 로 Promise 동일성을 비교했는데,
|
||||
// `.then(...)` 은 매번 새 Promise 를 반환 → 항상 false → cleanup 실패. 그래서 고유 symbol
|
||||
// 토큰을 부여하고 "내 토큰이 최신일 때만" 정리한다.
|
||||
|
||||
// 2) 의도적 graceful degradation — 빈 catch 에 이유 명시 (src/memory/index.ts)
|
||||
try { this.extractor.extractFromSession(...); }
|
||||
catch { /* memory extraction should never break the main flow */ }
|
||||
|
||||
// 3) ?? 로 의미 있는 0 보존 (src/retrieval/index.ts)
|
||||
const brainFileLimit = options.brainFileLimit ?? 8; // 명시적 0 = "검색 끔"
|
||||
|
||||
// 4) 단계 로그로 추적성 (src/retrieval/index.ts)
|
||||
fusionLog.push(`Brain search: ${brainChunks.length} chunks found`);
|
||||
fusionLog.push(`Selected: ${selectedChunks.length}, Dropped: ${dropped.length}, Tokens: ${tokensUsed}`);
|
||||
```
|
||||
|
||||
## ✅ 검증 상태 및 신뢰도
|
||||
- **상태:** draft
|
||||
- **검증 단계:** applied
|
||||
- **출처 신뢰도:** A
|
||||
- **신뢰 점수:** 0.93
|
||||
- **중복 검사 결과:** 신규 생성 (New discovery)
|
||||
|
||||
## 🔗 지식 그래프 (Knowledge Graph)
|
||||
- **상위/루트:** [[ConnectAI 아키텍처 개요]]
|
||||
- **관련 개념:** [[에러 처리와 커스텀 에러]], [[모듈 시스템과 프로젝트 구성]], [[프롬프트 엔지니어링 패턴]]
|
||||
- **참조 맥락:** 로컬 LLM 이 코드를 작성할 때 네이밍·주석·방어 코드의 스타일을 ConnectAI 와 일치시키도록 참조.
|
||||
|
||||
## 📚 출처 (Sources)
|
||||
- [S1] ConnectAI/src/core/lock.ts — post-mortem 주석, 모듈 헤더
|
||||
- [S2] ConnectAI/src/retrieval/index.ts — ?? 보존, 단계 로그, 상수 중앙화
|
||||
- [S3] ConnectAI/src/features/company/dispatcher.ts — 결정 근거 주석
|
||||
- [S4] ConnectAI/src/extension.ts — named export, 단일 진입점, void/getter 패턴
|
||||
|
||||
## 📝 변경 이력 (Change history)
|
||||
- 2026-06-13: ConnectAI 코드 분석 기반 초안 생성.
|
||||
@@ -0,0 +1,110 @@
|
||||
---
|
||||
id: prompt-engineering-patterns
|
||||
title: "프롬프트 엔지니어링 패턴"
|
||||
category: "AI_and_ML"
|
||||
status: "draft"
|
||||
verification_status: "applied"
|
||||
canonical_id: ""
|
||||
aliases: ["prompt engineering", "system prompt", "프롬프트 조립", "context block", "JSON output", "grounding", "프롬프트 설계"]
|
||||
duplicate_of: ""
|
||||
source_trust_level: "A"
|
||||
confidence_score: 0.91
|
||||
created_at: 2026-06-13
|
||||
updated_at: 2026-06-13
|
||||
review_reason: ""
|
||||
merge_history: []
|
||||
tags: ["prompt-engineering", "llm", "ai", "system-prompt", "connectai"]
|
||||
raw_sources: ["ConnectAI/src/intelligence/epistemicGuardBlock.ts", "ConnectAI/src/intelligence/correctionLoop.ts", "ConnectAI/src/intelligence/criticAgent.ts", "ConnectAI/src/features/datacollect/prompts/wikifyPrompt.ts", "ConnectAI/src/core/services.ts"]
|
||||
applied_in: ["ConnectAI"]
|
||||
github_commit: ""
|
||||
---
|
||||
|
||||
# [[프롬프트 엔지니어링 패턴]]
|
||||
|
||||
## 🎯 한 줄 통찰 (One-line insight)
|
||||
좋은 프롬프트는 "**조립 가능한 블록**으로 만들고(역할·규칙·컨텍스트·출력형식), 작은 모델일수록 system 으로 강하게 grounding 하고, 출력은 파싱 가능한 JSON/템플릿으로 강제하며, 결정론적 신호로 동적으로 강도를 조절"한다 — ConnectAI 의 검증 레이어가 이를 그대로 실천한다 [S1][S3][S4].
|
||||
|
||||
## 🧠 핵심 개념 (Core concepts)
|
||||
1. **블록 조립:** 시스템 프롬프트를 `[EPISTEMIC GUARD]`, `[MEMORY CONTEXT]`, `[자기검토]` 같은 명명 블록으로 만들어 필요 시 합친다 [S1][S5].
|
||||
2. **작은 모델엔 강한 system grounding:** gemma 류는 system 이 없으면 짧고 모호한 입력에 "시는 못 써드려요" 같은 환각 거절을 한다 — system 을 반드시 채운다 [S5].
|
||||
3. **출력 형식 강제:** "반드시 아래 JSON 만 출력" + 예시 스키마. 파싱은 균형 괄호 스캔으로 잡설 내성 [S3].
|
||||
4. **동적 강도 조절:** 검색 근거가 없을수록 가드 지시를 강화(`chunkCount === 0` 이면 "단정 금지·질문 우선") [S1].
|
||||
5. **few-shot 대신 규칙+제약:** 길고 명시적인 규칙 목록 + "근거 없으면 지어내지 말 것" 같은 negative constraint [S4].
|
||||
|
||||
## 🧩 추출된 패턴 (Extracted patterns)
|
||||
- **명명 블록 + 닫는 태그:** `[EPISTEMIC GUARD] ... [/EPISTEMIC GUARD]` — 모델이 블록 경계를 인식 [S1].
|
||||
- **3등급 인식론 강제:** 확실/추정/모름 등급 표시 — "모름 인정이 그럴듯한 오답보다 낫다" 를 명문화 [S1].
|
||||
- **조건부 블록 주입:** 통계가 임계(같은 태그 2회+)를 넘을 때만 자기검토 블록 주입 — 노이즈 방지 [S2].
|
||||
- **태그별 맞춤 지시:** 오류 태그(사실오류/근거누락…)마다 다른 자기검토 문장 매핑 [S2].
|
||||
- **system/user 분리 빌더:** `buildCritiquePrompt` 가 `{ system, user }` 를 반환 — 역할(검수자)과 데이터(초안)를 분리 [S3].
|
||||
- **입력 잘라내기(budget):** 초안/필드를 `maxDraftChars`/`MAX_FIELD_CHARS` 로 잘라 토큰·비용 통제 [S3].
|
||||
- **출력 후처리:** 작은 모델이 흘리는 `##`/`**` 마커를 사후 제거하고 history 에도 정제본만 저장(마커 재학습 방지) [참조: [[Agent 오케스트레이터 분해]]].
|
||||
|
||||
## 📖 세부 내용 (Details)
|
||||
### 왜 블록 조립인가
|
||||
한 턴의 system 프롬프트는 정체성·모드·메모리·가드·자기검토 등 여러 관심사가 합쳐진다. 각 관심사를 독립 빌더 함수(`buildEpistemicGuardBlock`, `buildSelfReviewBlock`)로 만들면, 조건에 따라 켜고 끄며 조합할 수 있고 단위 테스트가 쉽다 [S1][S2].
|
||||
|
||||
### 작은 모델 대응 (이 프로젝트의 핵심 제약)
|
||||
- system 으로 강하게 grounding (services.ts 주석: system 없으면 환각 거절) [S5].
|
||||
- 규칙을 *명시적이고 번호 매겨* 제시(wikify 프롬프트의 "필수 규칙 1~6 + 공통 규칙 7~15") [S4].
|
||||
- "본문에 없으면 지어내지 말고 '확인되지 않음' 표시" 같은 negative constraint 를 반복 [S4].
|
||||
- 출력 형식을 템플릿으로 못박고, 흘러나온 마커는 사후 정제.
|
||||
|
||||
### JSON 출력 + 강건 파싱
|
||||
"반드시 JSON 한 줄만" 을 지시해도 작은 모델은 코드펜스·잡설을 섞는다. 그래서 첫 균형 `{}` 블록을 스캔(문자열/이스케이프 인식)해 추출하고, 실패 시 휴리스틱 fallback 으로 분류한다 — *프롬프트와 파서를 함께 설계* [S3].
|
||||
|
||||
## ⚖️ 모순 및 업데이트 (Contradictions & updates)
|
||||
- **긴 프롬프트 vs 컨텍스트 한도:** 블록을 다 합치면 길어져 작은 모델의 컨텍스트를 압박한다. 그래서 [[RAG 검색 파이프라인]] 의 토큰 예산과 조건부 주입으로 길이를 통제한다.
|
||||
- **JSON 강제의 취약성:** 모델이 형식을 어기면 파싱 실패. 강건 파서 + fallback 이 필수 — "프롬프트만 믿지 말고 파서로 방어".
|
||||
- **few-shot 비용:** 예시를 많이 넣으면 정확하지만 토큰이 비싸다. ConnectAI 는 예시 최소화 + 규칙/제약 위주로 절충.
|
||||
|
||||
## 🛠️ 적용 사례 (Applied in summary)
|
||||
- `ConnectAI/src/intelligence/epistemicGuardBlock.ts` — 명명 블록, 동적 강도 [S1].
|
||||
- `ConnectAI/src/intelligence/correctionLoop.ts` — 조건부·태그별 자기검토 블록 [S2].
|
||||
- `ConnectAI/src/intelligence/criticAgent.ts` — system/user 분리, JSON 강제+강건 파싱 [S3].
|
||||
- `ConnectAI/src/features/datacollect/prompts/wikifyPrompt.ts` — 번호 규칙 + negative constraint + 템플릿 강제 [S4].
|
||||
|
||||
## 💻 코드 패턴 (Code patterns)
|
||||
```typescript
|
||||
// 1) 명명 블록 + 동적 강도 (src/intelligence/epistemicGuardBlock.ts)
|
||||
lines.push('[EPISTEMIC GUARD]');
|
||||
lines.push('- **모름 / 확인 필요** — 근거 없음. 지어내지 말고 "(확인 필요)" 표시.');
|
||||
if (signals.chunkCount === 0) lines.push('⚠️ 이번 턴은 검색 근거가 없음 — 단정하지 말 것.');
|
||||
lines.push('[/EPISTEMIC GUARD]');
|
||||
|
||||
// 2) 출력 형식 강제 (src/intelligence/criticAgent.ts)
|
||||
const system = [
|
||||
'너는 업무 산출물 검수자(Critic)다.',
|
||||
'반드시 아래 JSON 만 출력 (다른 텍스트 금지):',
|
||||
'{"pass": true|false, "issues": [{"severity":"major"|"minor","description":"..."}], "supplement":"..."}',
|
||||
].join('\n');
|
||||
|
||||
// 3) 작은 모델 grounding — system 필수 (src/core/services.ts 주석)
|
||||
// gemma 같은 작은 모델은 system 이 없으면 짧은/모호한 입력에 환각 거절을 하는 경향 → system 을 반드시 채운다.
|
||||
|
||||
// 4) 조건부 주입 — 임계 넘을 때만 (src/intelligence/correctionLoop.ts)
|
||||
const significant = profile.tagCounts.filter(t => t.count >= 2).slice(0, 2);
|
||||
if (significant.length === 0) return ''; // 1회성 실수로 프롬프트 어지럽히지 않음
|
||||
```
|
||||
|
||||
## ✅ 검증 상태 및 신뢰도
|
||||
- **상태:** draft
|
||||
- **검증 단계:** applied
|
||||
- **출처 신뢰도:** A
|
||||
- **신뢰 점수:** 0.91
|
||||
- **중복 검사 결과:** 신규 생성 (New discovery)
|
||||
|
||||
## 🔗 지식 그래프 (Knowledge Graph)
|
||||
- **상위/루트:** [[ConnectAI 아키텍처 개요]]
|
||||
- **관련 개념:** [[Intelligence 검증 레이어]], [[RAG 검색 파이프라인]], [[코딩 컨벤션과 주석 철학]], [[Reflection Pattern]], [[Critic Pattern]]
|
||||
- **참조 맥락:** 로컬 LLM 이 다른(또는 자기 자신) 모델을 호출하는 프롬프트를 설계할 때 참조.
|
||||
|
||||
## 📚 출처 (Sources)
|
||||
- [S1] ConnectAI/src/intelligence/epistemicGuardBlock.ts — 명명 블록, 3등급, 동적 강도
|
||||
- [S2] ConnectAI/src/intelligence/correctionLoop.ts — 조건부·태그별 자기검토 주입
|
||||
- [S3] ConnectAI/src/intelligence/criticAgent.ts — system/user 분리, JSON 강제+강건 파싱, 입력 budget
|
||||
- [S4] ConnectAI/src/features/datacollect/prompts/wikifyPrompt.ts — 번호 규칙, negative constraint, 템플릿
|
||||
- [S5] ConnectAI/src/core/services.ts — 작은 모델 system grounding 근거
|
||||
|
||||
## 📝 변경 이력 (Change history)
|
||||
- 2026-06-13: ConnectAI 코드 분석 기반 초안 생성.
|
||||
Reference in New Issue
Block a user