vima-tech/Innate

계층 역할

Innate은 보조적입니다. 절대 메인 작업을 차단해서는 안 됩니다. 모든 Innate 작업은 최선의 노력(best-effort)으로 처리됩니다. 도구 오류 발생 시: 수정된 호출로 한 번 재시도한 후, 포기하고 계속 진행합니다.

리콜 시점

다음과 같은 경우 작업 시작 시에만 리콜합니다:

• 작업 도메인이 알려진 반복 패턴(예: 특정 코드베이스, 프레임워크 또는 프로토콜)을 포함하는 경우
• 이전에 만났을 수 있는 문제를 디버깅하거나 수정하는 경우
• 아키텍처/설계 관련으로, 이전 결정이 중요한 경우

리콜 생략: 빠른 원라이너, 명확한 답변이 있는 질문, 사용자가 이전 컨텍스트 없이 완전히 새로운 영역으로 범위를 지정한 작업.

쿼리 공식화

**표준 의도(canonical intent)**를 사용하고, 사용자의 문자 그대로의 단어를 사용하지 마십시오. 세션 간에 쿼리를 일관되게 유지하십시오. 동일한 유형의 문제는 항상 동일한 표준 형식을 사용해야 합니다. Innate은 쿼리 패턴별로 컨텍스트 통계를 축적하기 때문입니다.

사용자 말	좋은 쿼리	나쁜 쿼리
"왜 시작시 충돌하나요?"	startup crash sqlite init	why does this crash on startup
"인증 플로우 리팩토링"	auth flow session token handling	refactor auth flow
"API에 속도 제한 추가"	rate limiting middleware pattern	add rate limiting
"불안정한 테스트 디버깅"	flaky test race condition timing	debug flaky test

호출: innate_recall(query=<표준_의도>, budget=4000, source="mcp")

리콜된 청크를 작업 컨텍스트에 주입하십시오. 관련 사전 지식이 발견된 경우 사용자에게 (어떤 것이든) 언급하십시오. 한 문장이면 충분합니다.

자동 리콜 훅

Innate이 훅과 함께 설치된 경우, UserPromptSubmit 훅이 자동으로 <innate-recall> 블록을 대화에 주입할 수 있습니다. 이 블록은 프롬프트에 대한 관련성 게이트 리콜을 이미 실행했으며 trace_id를 전달합니다. 해당 블록이 보이면:

• 해당 블록의 **trace_id**를 종료 innate_record에 재사용하십시오. 동일한 작업에 대해 innate_recall을 다시 호출하지 마십시오 (중복되고 매달린 추적이 생성됨).
• 청크를 직접 리콜한 것처럼 정확히 처리하십시오: 도움이 되는 것을 적용하고, 아래의 청크별 평결로 마무리하십시오.
• 블록이 없고 작업이 필요한 경우, 위와 같이 수동으로 리콜하십시오.

훅은 관련성 게이트이므로, 훅의 침묵은 "점수가 높은 것이 없다"는 의미이지 "지식이 없다"는 의미가 아닙니다. 게이트가 놓친 관련 사전 지식이 의심되면 수동으로 리콜하십시오.

기록 시점

실제 결과(성공 또는 실패)를 생성한 작업 후에 기록합니다. 다음의 경우 기록을 건너뜁니다:

• 확정적인 결과 없는 탐색적 논의
• 사용자가 완료 전에 중단한 작업
• 순수 검색(사용자가 질문만 하고, 아무것도 구축하거나 변경하지 않음)

결과 규칙

상황	결과(outcome)
작업 완료, 사용자가 결과를 확인하거나 수락함	ok
작업 실패, 접근 방식이 틀렸고 사용자가 수정해야 했음	fail
세션 중단, 결과 불명확	unknown

청크별 평결 — 필수

이는 Innate에서 가장 중요한 단일 규칙입니다: 신뢰도 순위는 여기에 보고하는 정밀도에 의해서만 결정됩니다. 청크를 표면화한 모든 리콜(수동 또는 훅 주입)은 청크별 평결로 마무리되어야 합니다. 여러분 앞에 놓인 각 청크는 정확히 세 개의 버킷 중 하나에 속합니다:

평결	의미	위치
사용됨 + 도움됨	적용했고 시간을 절약하거나 실수를 방지함	used=[id] 및 feedback_up=[id]
사용됨 + 오해 유발	적용했지만 틀렸거나 잘못된 방향으로 이끌림	used=[id] 및 feedback_down=[id]
사용 안 함	리콜되었지만 적용하지 않음	완전히 생략(used에 나열하지 마십시오)

신호를 깨끗하게 유지하는 규칙:

• used는 추론이나 출력에서 적극적으로 참조한 청크만 나열합니다. 일반적으로 1~3개입니다. 단순히 리콜된 청크로 채우지 마십시오.
• 아무것도 적용하지 않았다면, 이는 실제적이고 가치 있는 신호입니다: used=[]를 명시적으로 설정하십시오(알려진 없음). 기록을 건너뛰지 마십시오 — 침묵은 "도움된 것 없음"과 같지 않습니다.
• 사용됨 청크는 거의 항상 상승 또는 하강 신호를 전달해야 합니다. 평결 없이 사용된 청크는 제공할 수 있는 가장 강력한 순위 입력을 낭비하는 것입니다.
• feedback_down에 대해 정직하십시오. 표시된 잘못된 청크는 검토 및 아카이빙됩니다. 표시되지 않은 잘못된 청크는 미래 세션을 계속 오도합니다.

출력 요약 — 구조화된 형식

미래 에이전트가 냉담한 상태에서도 실행할 수 있는 자체 완결적 문장을 작성하십시오. 다음 구조를 사용하십시오:

<수행되거나 배운 것> — <핵심 제약 또는 방법> — <이것이 적용되는 시점>

좋은 예:

• SQLite WAL 모드 탐지를 PRAGMA journal_mode 응답 확인으로 수정, WAL을 가정하지 않음 — 다중 프로세스 설정의 새로운 DB 연결에서 트리거됨
• 클록 모의 객체 주입으로 불안정한 인증 테스트 해결 — 실제 시스템 시간이 토큰 만료 확인에서 경합 상태를 유발함
• 속도 제한은 인증 미들웨어 후가 아닌 전에 적용해야 함 — 그렇지 않으면 인증되지 않은 요청이 제한기를 우회함

나쁜 예(재사용하기에 너무 모호함):

• 버그 수정함
• 사용자가 인증 관련 도움을 요청함
• 문제는 타이밍이었음

output_summary는 재사용 가능한 지식 청크가 됩니다. 이야기처럼 읽히면 원칙으로 다시 작성하십시오. 일반적이고 전이 가능한 형태를 선호하십시오 — repo/파일/함수 이름 및 일회성 식별자를 제거하고, 다음 프로젝트에도 도움이 되도록 교훈을 표현하십시오. 교훈이 의미를 잃지 않고 일반화할 수 없는 경우에만 프로젝트별 세부 정보를 유지하십시오. 유용한 요약을 작성할 수 없으면, output="unknown"으로 설정하고 기록을 건너뛰십시오.

호출: innate_record(trace_id=<id>, outcome=<ok|fail|unknown>, used=[<chunk_ids>], output_summary=<문장>)

명시적 피드백 — 중요한 이유

위의 평결 테이블에서 feedback_up / feedback_down 목록은 지식 품질에 대한 가장 빠른 신호이며, 순위 및 수명 주기를 직접적으로 유도합니다: 동일한 청크에 대한 두 개의 하강 신호는 거버넌스 검토를 트리거합니다. 다섯 개는 자동 아카이빙을 트리거합니다. 반대로, 반복된 사용됨 + feedback_up은 pending 청크를 active로 승격시킵니다. 피드백을 보류하면 지식 베이스가 고정됩니다. 피드백을 제공하는 것이 좋은 지식이 상승하고 나쁜 지식이 사라지는 방법입니다.

지명 — 드물고, 명시적

nomination 필드는 진정으로 일반화 가능한 교훈에만 사용하십시오. 이 유형의 문제가 다음에 나타날 때 상당한 시간을 절약할 패턴. 드뭅니다. 모든 작업에 사용하지 마십시오.

지명 형식 (자체 완결적 원칙):

<원칙> — <적용되는 시점> — <피해야 할 것>

예시:

innate_record(..., nomination="부분 WHERE 절의 SQLite UNIQUE 인덱스는 ON CONFLICT에서 정확한 WHERE 일치가 필요함 — 모든 upsert 패턴에 적용됨. WHERE 없이 ON CONFLICT만 사용하면 upsert가 자동으로 건너뛰어짐")

MCP 도구 참조

도구	사용	참고
innate_recall	작업 시작 시 (관련 있는 경우)	표준 쿼리 형식 사용 — 일관된 표현이 컨텍스트 통계를 축적함
innate_record	작업 종료 시 (실제 결과가 있는 경우)	구조화된 output_summary + 정확한 사용된 ID
innate_add	확인된 통찰 캡처	항상 source="mcp"; pending 상태로 전환, 검토 대기
innate_spark	빠른 아이디어 추후 저장	간결한 정제된 형태; 검토 불필요
innate_evolve	세션 종료 시	trigger="manual"; 로그 정제 + 지식 베이스 큐레이션
innate_inspect	상태 확인	청크 수, 부채 비율, 재구축 큐
innate_appraise	위험한 단계 전 직감 확인	참조 신호 전용 — 직관, 정확한 답변이 아님. 하나의 입력으로 가중치를 두되, 자신의 분석을 절대 덮어쓰지 마십시오. abstained=true는 근거가 없음을 의미 — 이는 올바른 동작이지 실패가 아님

명시적 사용자 요청 없이 호출 금지: innate_approve, innate_archive, innate_invalidate, innate_restore, innate_mature_spark, innate_promote_spark, innate_drop_spark.

기록 결정

긴 세션을 종료하기 전에 다음 체크리스트를 자동으로 실행하십시오:

1. 명확하지 않은 해결책이 발견되었습니까? (해결 방법, 숨겨진 제약, 미묘한 버그 패턴)
2. 일반적이고 전이 가능한 스킬, 방법 또는 기술이 표면화되었습니까? (이것들을 선호하십시오 — 프로젝트별 교훈을 재사용 가능한 형태로 추상화하십시오. 진정으로 일반화할 수 없는 경우에만 프로젝트별 규칙을 유지하십시오)
3. 사용자가 내가 반복할 가능성이 있는 잘못된 가정을 수정했습니까?
4. 여러 번의 실패 시도 끝에 간신히 얻은 통찰이 있습니까?
5. 리콜된 청크가 적극적으로 도움이 되었습니까? (feedback_up 기록)
6. 리콜된 청크가 오해를 불러일으켰습니까? (feedback_down 기록)

1-4 중 하나라도 해당되면 사용자에게 제안하십시오:

"이 세션에서 [한 줄 설명]이 표면화되었습니다. Innate에 저장할까요?"

사용자가 확인한 후에만 innate_spark 또는 innate_add를 호출하십시오. 절대 자동으로 기록하지 마십시오.

축어 금지 규칙

원시 대화 텍스트는 절대 저장해서는 안 됩니다. 항상 재사용 가능한 원칙 형태로 정제하십시오:

<원칙> — <트리거 컨텍스트> — <피해야 할 것>

❌ 축어	✅ 정제됨
"사용자가 WAL 모드를 사용하라고 했고, pragma를 변경하여 수정했습니다"	"SQLite WAL 모드는 PRAGMA 응답으로 확인해야 하며 가정해서는 안 됨 — 쓰기 위주 다중 프로세스 설정에서 DB 열기 시 트리거됨"
"시계 차이로 인해 인증 디버깅에 2시간을 소비했습니다"	"JWT 검증은 시계 차이 허용 오차(≥30초)를 고려해야 함 — 독립적인 시스템 시계를 가진 서비스 간 분산 인증에서 트리거됨"

일반적인 것을 프로젝트별보다 선호

Innate은 일반적이고 전이 가능한 스킬, 방법 및 기술에 편향되어 있습니다. 즉, 현재 코드베이스뿐만 아니라 프로젝트 전반에 걸쳐 성과를 내는 지식입니다. 교훈이 프로젝트별인 경우:

1. 추상화를 시도하십시오 — repo/파일/함수/경로 이름 및 일회성 식별자를 제거하고, 다음 프로젝트가 재사용할 수 있는 원칙으로 다시 표현하십시오.
2. 추상화된 형태를 저장하십시오. 교훈이 의미를 잃지 않고 일반화할 수 없는 경우에만 구체적인 프로젝트별 세부 정보를 유지하십시오.

❌ 프로젝트 경계	✅ 일반화됨
"이 repo에서, record()는 BEGIN IMMEDIATE 내에서 실행되어야 합니다"	"원자성을 가져야 하는 다단계 상태 변이는 단계별 커밋이 아닌 하나의 독점 트랜잭션에 속함 — 동시 프로세스가 있는 모든 SQLite 작성기에 적용됨"
"메타 테이블에서 recall.budget=4000을 설정하십시오"	"검색 예산을 하드코딩하는 대신 조정 가능한 매개변수로 노출하십시오 — 코드 변경 없이 컨텍스트 창에 따라 리콜 규모를 조정 가능"

스파크 vs. 노트

innate_spark 사용	innate_add 사용
빠른 아이디어, 반쯤 형성된 직감	확인된 재사용 가능 원칙
아직 검증되지 않음	이 세션에서 검증됨
사용자가 "나중을 위해 이것을 메모해"라고 말함	사용자가 "이 규칙을 기억해"라고 말함

CLI 폴백 (MCP가 구성되지 않은 경우)

# 리콜
innate recall "<표준_의도>" --top 5 --format json --source cli

# 구조화된 요약으로 기록
innate record <trace_id> --outcome ok \
  --used <id1>,<id2> \
  --output-summary "Y를 수행하여 X 수정 — Z에 적용됨" \
  --feedback up  # 또는 down

# 통찰 캡처
innate add "<원칙> — <트리거> — <피해야 할 것>" \
  --trigger "<2-5 단어 컨텍스트>" \
  --source agent

# 빠른 스파크
innate spark "<1-2 문장으로 정제된 아이디어>"

# 세션 종료
innate evolve --trigger manual
innate inspect

명령어

아래의 슬래시 명령어는 innate install에 의해 ~/.claude/commands/에 자동으로 설치되며, innate install이 다시 실행될 때마다 업데이트됩니다. 각 command 블록은 하나의 명령어를 정의합니다: --- 앞의 메타데이터, --- 뒤의 본문(에이전트 프롬프트).

name: innate-recall
description: 현재 작업 컨텍스트에 대한 이전 Innate 지식 리콜
---
현재 작업 컨텍스트에 대해 innate_recall을 실행하고 결과를 이 대화에 주입하십시오.

사용자가 명령어 뒤에 쿼리를 제공한 경우, 해당 쿼리를 정확히 리콜 쿼리로 사용하십시오.
쿼리가 제공되지 않은 경우 ($ARGUMENTS가 비어 있음), 가장 최근 사용자 메시지 또는 현재 작업 의도에서 쿼리를 추론하십시오 — **표준 의도**를 사용하십시오(예: `why does this crash` 대신 `sqlite wal mode init`). 쿼리 형식을 미래에 동일한 유형의 문제를 표현하는 방식과 일관되게 유지하십시오.

단계:
1. 표준 쿼리 문자열을 공식화하십시오 ($ARGUMENTS 또는 추론된 의도로부터).
2. `query=<쿼리>`, `budget=4000`, `source="mcp"`로 `innate_recall`을 호출하십시오.
3. 지식이 반환된 경우: 발견된 내용을 한 문장으로 요약한 후, 관련 청크를 컨텍스트에 주입하십시오.
4. 비어 있는 경우: "<쿼리>에 대한 이전 지식을 찾을 수 없습니다."라고 말하고, 지어내지 마십시오.
5. 추후 `/innate-record`에서 사용할 `trace_id`를 저장하십시오.

name: innate-record
description: 결과와 구조화된 요약으로 현재 Innate 추적 종료
---
결과와 요약으로 현재 Innate 추적을 종료하십시오.

$ARGUMENTS를 구문 분석:
- outcome: `ok`, `fail`, `unknown` 중 하나 (지정되지 않은 경우 기본값: `ok`)
- 나머지 텍스트는 output_summary 재정의가 됨

단계:
1. 이 세션의 가장 최근 `innate_recall` 호출에서 활성 trace_id를 식별하십시오.
   trace_id를 사용할 수 없는 경우 "활성 추적이 없습니다 — 먼저 /innate-recall을 실행하십시오."라고 말하십시오.
2. 최종 응답에서 **실제로 사용된** 리콜 청크 ID를 결정하십시오 (단순히 후보였던 것은 제외). 정확하십시오 — 사용되지 않은 리콜 청크는 나열해서는 안 됩니다.
3. 냉담한 상태에서 읽는 미래 에이전트를 위한 구조화된 output_summary를 작성하십시오:
   형식: `<수행된 것> — <핵심 제약/방법> — <이것이 적용되는 시점>`
   사용자가 $ARGUMENTS에 요약 텍스트를 제공한 경우, 이를 사용하십시오.
4. 피드백 평가:
   - 어떤 청크가 직접적으로 도움이 된 경우 → `feedback_up=[chunk_id]` 포함
   - 어떤 청크가 틀렸거나 오해를 불러일으킨 경우 → `feedback_down=[chunk_id]` 포함
5. `trace_id`, `outcome`, `used=[<chunk_ids>]`, `output_summary` 및 해당되는 경우 피드백을 사용하여 `innate_record`를 호출하십시오.
6. 확인: "추적 <trace_id>를 <outcome>으로 기록했습니다."

name: innate-save
description: 확인된 통찰을 보류 중인 지식 청크로 Innate에 저장
---
확인된 통찰을 보류 중인 지식 청크로 Innate에 저장하십시오.

$ARGUMENTS는 저장할 통찰 텍스트입니다 (필수). 비어 있는 경우, "어떤 통찰을 저장하시겠습니까?"라고 물으십시오.

단계:
1. $ARGUMENTS를 통찰 내용으로 구문 분석하십시오.
2. 정제하십시오: 축어 금지 규칙 및 일반화 규칙을 적용하십시오.
3. `innate_add`를 호출하여 통찰을 저장하십시오.
4. 확인: "통찰 '[...]'을(를) Innate에 저장했습니다."