k-layer

Imported from LowyShin/giip-fde-agent (.agent/skills/k-layer/SKILL.md). Install upstream with npx skills add LowyShin/giip-fde-agent --skill k-layer. Copyright stays with the author.

K-Layer: 에이전트 자동 지식 생성 시스템

카파시 다이어그램의 핵심 원리를 에이전트에 적용합니다. 사람이 위키를 쓰는 게 아니라, 에이전트가 데이터를 읽고 위키를 씁니다.

🔑 핵심 원칙

Raw Traces/Results → LLM Analysis → Source-Linked Claims → K-Layer Wiki → Next Task Context

1. Source-linked claims: 모든 주장에 원본 근거(파일명, trace_id, 커밋 해시) 링크 필수
2. Immutable append-only: Claim 삭제 금지. invalidated_at 필드로만 무효화
3. 자기강화 루프: 새 작업 시작 전 관련 K-Layer 노트 참조 필수
4. Raw는 보존: K-Layer는 raw 위에 올라가는 정제 계층. raw를 대체하지 않음
5. 프로젝트 경계: 작업 전 검색은 현재 작업공간의 .agent/knowledge/notes만 조회합니다. 프로젝트와 CSN이 다른 claim을 절대 합치지 않습니다. 범위가 없는 과거 claim은 giip-fde-agent 저장소에서만 참조합니다.
6. 신선도와 예산: invalidated_at이 null인 claim만 유효합니다. expires_at이 지난 claim, review_due_at에 재확인이 완료되지 않은 claim, 검증 가능한 source_hash와 실제 파일 해시가 다른 claim은 제외합니다. 검색은 최대 10건, 1600자로 제한합니다.

📥 1단계: K-Layer 노트 참조 (작업 시작 전)

새 작업 시작 시, 관련 K-Layer 노트가 있는지 확인합니다:

# 관련 키워드로 지식 노트 검색
Get-ChildItem ".agent/knowledge/notes/" -Recurse | 
  Select-String -Pattern "관련_키워드" | 
  Select-Object Filename, LineNumber, Line

참조한 claim이 있으면 작업 컨텍스트에 명시적으로 포함:

"K-Layer 참조: CLAIM-003 (source: notes/api-errors.md#claim-003) — Azure Function cold start는 30초 이상 소요됨"

📤 2단계: Claim 생성 (작업 완료 후)

작업 결과에서 재사용 가능한 패턴/교훈을 발견하면 claim으로 변환합니다.

Claim 형식

## [주제 제목]

CLAIM-{NNN}: {관찰된 사실 또는 패턴}
- **evidence**: {구체적 수치나 관측값}
- **source**: {파일명#라인번호 또는 trace_id#step}
- **observed_at**: {YYYYMMDD}
- **invalidated_at**: null  ← 항상 null로 시작, 무효화 시만 날짜 기입
- **confidence**: high|mid|low
- **project**: {현재 작업공간 이름; 고객별 필수}
- **csn**: {CSN; 확인 가능한 경우 기록, 해당 CSN 작업에서만 조회}
- **expires_at**: {YYYY-MM-DD; 재검증 기한이 있는 사실에서만 지정}
- **review_due_at**: {YYYY-MM-DD; 이날부터 재검증 완료 전까지 검색 제외, 검증 후 새 기한 기록}
- **source_file**: {현재 작업공간 상대경로; 로컬 원본 해시를 쓰는 경우}
- **source_hash**: {source_file 전체 내용의 SHA-256; 변경 시 자동 제외, 선택 사항}

예시

project는 고객 작업공간에 새 claim을 쓸 때 반드시 기록합니다. CSN을 모르는 경우 추측해서 채우지 말고 비워 두며, CSN을 기록한 claim은 정확히 일치하는 CSN에서만 검색합니다. expires_at은 사실의 유효기간 종료일(해당 날짜까지 검색 가능), review_due_at은 재검증 시작일(해당 날짜부터 검색 제외)입니다. 두 필드의 날짜가 잘못되면 검색에서 제외합니다. source_file과 source_hash는 함께 기록하며, 해시 검사는 2 MiB 이하의 작업공간 내부 파일에만 적용합니다. 큰 파일이나 작업공간 밖 원본은 해시를 만들지 않고 기존 source 근거와 재검증 기한을 기록합니다.

## API 오류 패턴

CLAIM-001: GIIP API는 Authorization 헤더 없이 호출 시 401이 아닌 403 반환
- **evidence**: 3회 관측 (20260129, 20260201, 20260204)
- **source**: giipfaw/giipIssues/run.ps1#L23, traces/20260129_auth_fix.json#step-3
- **observed_at**: 20260204
- **invalidated_at**: null
- **confidence**: high

CLAIM-002: Azure Function cold start는 첫 호출 시 평균 25-35초 지연 발생
- **evidence**: 테스트 5회 측정 평균 28.4초
- **source**: traces/20260204_cold_start_test.json#step-7
- **observed_at**: 20260204
- **invalidated_at**: null
- **confidence**: mid

💾 3단계: 지식 노트 저장

저장 경로: .agent/knowledge/notes/{topic}.md

주제별 파일 분류

🔄 4단계: 자기강화 루프

새 작업 요청
    ↓
K-Layer 노트 검색 (관련 topic 키워드)
    ↓
관련 claim 발견? → 컨텍스트에 포함
    ↓
작업 실행
    ↓
새로운 패턴/교훈 발견?
    ├── Yes → Claim 생성 → K-Layer 노트에 append
    └── No  → 기존 claim 신뢰도 갱신 (evidence 보강)

⚡ 빠른 실행 명령어

/k-layer search {키워드} — 관련 knowledge 검색

Select-String -Path ".agent/knowledge/notes/*.md" -Pattern "{키워드}"

/k-layer add {topic} — 새 claim 추가

현재 작업 결과를 분석하여 .agent/knowledge/notes/{topic}.md에 claim 생성

/k-layer invalidate {topic} {CLAIM-NNN} — claim 무효화

# CLAIM-001의 invalidated_at을 오늘 날짜로 업데이트
(Get-Content ".agent/knowledge/notes/{topic}.md") -replace '(CLAIM-001.*\r?\n.*invalidated_at): null', '$1: 20260415' | 
  Set-Content ".agent/knowledge/notes/{topic}.md"

/k-layer summary — 전체 knowledge 현황 요약

$notes = Get-ChildItem ".agent/knowledge/notes/" -Filter "*.md"
$total = ($notes | Get-Content | Select-String "^CLAIM-").Count
$active = ($notes | Get-Content | Select-String "invalidated_at: null").Count
Write-Host "총 Claim: $total | 활성: $active | 무효화: $($total - $active)"

📋 GEMINI.md 통합 규칙

이 스킬은 다음 상황에서 자동으로 트리거됩니다:

1. 반복 오류 발견 시: 동일 오류가 2회 이상 발생하면 K-Layer에 기록
2. 작업 완료 후: 새로운 기술적 사실이 발견되면 claim 생성
3. 새 작업 시작 전: 관련 topic의 K-Layer 노트 조회

⚡ Optimization Integration

When using this skill for critical tasks, please run it within a /native-trace context to capture performance data for self-improvement via /aioptimize.