# Kodex Knowledge System

## 핵심 원칙

**너는 이 프로젝트의 장기 기억이다.** 세션이 끝나면 너의 컨텍스트는 사라지지만, `kodex-out/` 에 저장한 지식은 남는다. 다음 세션의 너(또는 다른 AI)가 이 지식을 읽고 이어간다.

저장할지 말지는 **너가 판단**한다. 규칙은 단순하다:

> "다음 세션의 나에게 이걸 알려주면 도움이 될까?"
> 그렇다면 저장하라.

## 세션 시작 시

1. `kodex-out/_KNOWLEDGE_INDEX.md` **한 파일만** 읽어라. 축적된 지식의 요약이다.
2. 특정 항목의 상세가 필요할 때만 개별 `_KNOWLEDGE_*.md` 를 읽어라.
3. `kodex-out/GRAPH_REPORT.md` 를 읽어라. 프로젝트 구조 개요다.

> **토큰 절약**: 개별 파일을 전부 읽지 마라. INDEX가 전체 요약이다.

## 저장 기준

아래에 해당하면 저장하라. **목록에 없는 것도 가치 있다고 판단되면 저장하라.**

- 코드를 읽다 파악한 아키텍처, 설계 의도, 숨겨진 전제
- 사용자가 말한 요구사항, 제약 조건, 우선순위
- 버그를 고치면서 알게 된 원인과 해결 방법
- 사용자의 코딩 스타일, 선호, 싫어하는 것
- 모듈 간 의존 관계, 변경 시 영향 범위
- 도메인 용어와 비즈니스 규칙
- "이건 나중에 문제될 수 있겠다" 싶은 기술 부채
- 이전 세션에서의 결정 사항과 그 이유
- 테스트 전략, 배포 절차, 환경 설정 관련 지식
- 외부 API, 서드파티 서비스의 특이 사항
- 성능 병목, 최적화 기회
- 프로젝트의 미래 방향, 로드맵, TODO

## 저장 방법

파일명: `kodex-out/_KNOWLEDGE_<제목>.md`

```markdown
---
type: knowledge
knowledge_type: <아래 중 하나>
confidence: 0.50
observations: 1
first_seen: <unix_timestamp>
last_seen: <unix_timestamp>
tags: [태그1, 태그2]
related_nodes: [관련_노드_id]
---

# 제목

구체적으로 기술. 왜 중요한지, 어떤 맥락에서 알게 됐는지.

## Related

[[관련_노드]] [[관련_노드2]]
```

### knowledge_type 값

| Type | 설명 |
|------|------|
| `architecture` | 시스템 구조, 레이어, 모듈 구성 |
| `pattern` | 디자인 패턴, 반복되는 구조 |
| `decision` | 설계 결정과 그 이유 (ADR) |
| `convention` | 코딩 컨벤션, 명명 규칙, 스타일 |
| `coupling` | 모듈 간 의존, 변경 전파 경로 |
| `domain` | 도메인 용어, 비즈니스 룰, 상태 머신 |
| `preference` | 사용자 선호, 작업 방식 |
| `bug_pattern` | 반복되는 버그 유형, 취약 지점 |
| `tech_debt` | 기술 부채, 리팩토링 필요 지점 |
| `ops` | 배포, 인프라, 환경 설정, CI/CD |
| `api` | 외부 API 특이사항, 제한, 인증 방식 |
| `performance` | 병목, 최적화, 벤치마크 결과 |
| `roadmap` | 미래 계획, TODO, 마일스톤 |
| `context` | 프로젝트 배경, 팀 구조, 이해관계자 |
| `lesson` | 실패에서 배운 교훈, 삽질 기록 |

새로운 type이 필요하면 만들어라. 위 목록에 없어도 된다.

## 기존 지식 강화

같은 주제를 다시 만나면 **새 파일을 만들지 말고** 기존 파일을 수정:

- `observations` += 1
- `confidence` = 1.0 - (1.0 - 현재) * 0.8
- `last_seen` 갱신
- 새 내용을 `---` 구분자로 추가
- `related_nodes` 에 새 노드 추가

## 하지 말 것

- 코드 자체를 복사해서 저장하지 마라. 코드는 코드에 있다.
- 너무 세부적인 구현 디테일은 저장하지 마라. git log에 있다.
- 확실하지 않은 추측은 confidence를 낮게 (0.3) 설정하라.
- 모든 것을 저장하려 하지 마라. 다음 세션에 도움될 것만.
