Pi × EvoX Loop — 지능체 경험 상속 Skill

Agent가 각 함정을 한 번만 밟게 하세요: 실패 경험은 자동으로 저장소에 기록(가드 필터링)되고, 유사 작업 시 검증된 수정 방법이 자동으로 불러와집니다.

용어 규약(0.29): 본문은 한국어를 중심으로 하며, 기술 필드는 처음 등장할 때 영어 원문을 한 번 표기(예: '신호 매칭 signals_match')한 후, 이후에는 모두 한국어로 통일하고 혼용하지 않습니다. 완전한 한영 대조는 docs/faq.md Q17을 참조하세요.

문서 맵(0.21 계층):

신규 사용자는 세 섹션만 읽으면 됩니다: 30초 사용법 → 흐름 A → 흐름 B(약 60줄); 나머지는 필요에 따라 참조.

1분 만에 사용 여부 판단: docs/one-pager.md(0.30 신규)

모범 사례 집중 진입: examples/quickstart.md(5분 완결) + docs/overview.md(프로젝트 개요) + docs/common-mistakes.md(14가지 안티패턴) — 세 가지로 '시작/전체/함정 피하기'를 다룹니다.

본 파일의 나머지 부분 = 트리거 포인트/보안 요약/안티패턴 빠른 검색/내비게이션; docs/advanced.md = 역채움 주소 지정/타임라인/harvest/동시성 잠금/공유 라이브러리/호스트 연동/운영/보안 게이트 상세; docs/common-mistakes.md = 일반적인 오용 사례 전체 목록; docs/config-errors.md = 일반적인 설정 오류; docs/faq.md = 전체 FAQ.

docs/research.md = 흐름 C 통제 실험 + 함정 설계 규율 — 연구 전용, 대부분의 사용자는 열 필요 없음.

30초 사용법 (Quick-Start)

EN: Requires Node >= 22. Optional @evomap/evolver integration is GPL-3.0-or-later (only if you install and use --engine evolver); the default light backend is MIT, zero-dependency, zero-exfiltration. Three things only: A recall validated fixes at task start, B deposit after fixing a non-obvious failure, C (optional, research) controlled experiments. Daily use = A/B only. ⚠️ 전제 조건: Node ≥ 22(node -v 확인; 이전 버전은 지원되지 않으며, 먼저 업그레이드해야 함). 선택적 통합 @evomap/evolver는 GPL-3.0-or-later입니다 — 사용자가 직접 설치하고 --engine evolver를 사용할 때만 적용되며, 기본 light 백엔드는 MIT, 제로 종속성, 제로 외부 전송입니다.

이 Skill은 세 가지만 수행합니다: A 작업 시작 시 검증된 수정 사항 불러오기, B 오류 수정 후 축적, C (선택 사항, 연구용) 통제 실험으로 이득 정량화. 일상적으로는 A/B만 사용하며, C는 기본적으로 모두 꺼져 있으므로 프로덕션에 사용하지 마십시오.

# A — 작업 시작 시 타겟 검색 (자신의 작업 한 줄로 대체)
node code/evolver-recall.mjs --query "GBK 인코딩 파일 처리 오류" --top 5

# B — 명백하지 않은 오류를 수정한 후, 원래 오류 메시지를 붙여 초안 생성, 그런 다음 FIX를 추가하여 저장소에 저장
node code/light-cli.mjs draft --error "<원본 오류>" --tool <도구명> --context "<당시 수행 중인 작업>"
node code/light-cli.mjs draft --error "<원본 오류>" --strategy "AVOID: <하지 말아야 할 것> FIX: <구체적인 매개변수/명령/인코딩>" --commit

명령은 모두 이 저장소의 루트 디렉토리에서 실행합니다. 종속성이 설치되지 않은 경우 아래 '설치'를 먼저 참조하십시오.

첫 실행 · 3단계 준비 (먼저 자체 점검, 그 다음 축적)

Node ≥22 설치(트랩 생성기와 pi/evolver 모두 필요; FAQ·Q8 참조);
환경 자체 점검: node code/light-cli.mjs doctor — Node 버전, 경험 라이브러리 디렉토리 쓰기 가능, 히트 등록 디렉토리 접근 가능 확인(실패 시 수정 안내 제공);
경험 라이브러리 활성화: 빈 라이브러리에서 불러올 수정 사항이 없는 것은 정상입니다. 아래 흐름 B에 따라 첫 번째 수정 사항을 축적하면 활성화됩니다.

초보자 필독 (자주 묻는 질문 요약)

처음 실행 시 '불러올 수정 사항 없음' 메시지? 정상입니다 — 라이브러리는 처음부터 시작하므로, 먼저 B를 한 번 실행하여 축적하면 활성화됩니다(FAQ·Q1).
Node 버전 요구 사항? ≥22 필요(트랩 생성기는 Python 3도 필요), 너무 낮으면 pi/evolver 시작에 실패합니다(FAQ·Q8).
더 많은 질문은 docs/faq.md(전체 14개 항목)와 아래의 안티패턴 빠른 검색을 참조하십시오.

설치 (일회성)

EN: One-time setup. A/B flows need ONLY Node >= 22 — zero npm dependencies. Get the folder by any of three paths below; any location works (a "skill" is just a folder — put it wherever your host expects, e.g. ~/.claude/skills/pi-evox-lab). Default backend = built-in light (pure Node, MIT). evolver is an optional integration (--engine evolver, needs npm install). Flow C additionally needs Pi CLI + an OpenAI-compatible LLM key.

세 가지 획득 경로(하나 선택)

# 경로 1: git clone(권장)
git clone https://github.com/stwhwing/pi-evox-lab.git && cd pi-evox-lab
# 경로 2: 제한된 네트워크 → Release zip 직접 다운로드(sha256 첨부), 압축 풀고 즉시 사용
#   https://github.com/stwhwing/pi-evox-lab/releases (국내 접속 가능 미러는 FAQ Q7 참조)
# 경로 3: 마켓 원클릭 설치 — skillhub.cn / ClawHub에서 pi-evox-loop 검색(WorkBuddy/OpenClaw 사용자)

node -v                # 전제 조건: Node >= 22(유일한 하드 종속성)
node code/light-cli.mjs doctor   # 30초 자체 점검 — 통과하면 사용 가능, 설치 단계 필요 없음

A/B 일상 흐름은 npm 종속성 제로; 아래 npm install은 선택적 통합/실험 모드 C를 위한 준비일 뿐입니다:

Provider 설정 (흐름 C에만 필요)

EN: Flow C only - any OpenAI-compatible endpoint; $ENV interpolation needs pi >= 0.85.1. Examples + domestic endpoints (DeepSeek/Bailian/SiliconFlow/Zhipu): docs/providers.md.

흐름 A: 작업 시작 — 경험 불러오기 (모든 비사소한 작업)

EN: Flow A - recall at task start. --query with the task text does targeted recall (unrelated experience is never injected - injection is gated by signals_match x query-token overlap, below threshold = no injection). On error (T3), the raw error text IS the query. Multiple matches: geneConflicts drops anti_patterns-mutual low scorers; no targeted hit = no injection. Register the hit at task end with --register-hit --gene <id> (id-addressed, concurrency-safe).

# 국내 빈번한 시나리오 (중국어 Windows 로그 / CSV 기본 GBK, utf-8로 읽으면 반드시 깨짐) — 빈 라이브러리에서 starter 실행 후 먼저 이 명령어 시도가 가장 효과적
node code/evolver-recall.mjs --query "중국어 로그 읽기 시 UnicodeDecodeError 발생" --top 5

# 권장: 작업 텍스트를 사용한 '타겟' 불러오기 (작업과 관련 없는 경험은 주입되지 않음)
node code/evolver-recall.mjs --query "<현재 작업 한 줄/핵심 신호>" --top 5

# 오류 발생 시(T3): 오류 원문이 곧 쿼리 — 오류 자체가 알림 역할
node code/evolver-recall.mjs --error "UnicodeDecodeError: 'utf-8' codec can't decode byte 0xc4"

'검토됨 그리고 수정 가드 통과 그리고 쿼리와 타겟 매칭'된 번호가 매겨진 수정 사항 목록만 출력합니다(빈 라이브러리는 명확한 메시지를 표시하며, 정상입니다);
매개변수 기본값: --top 기본 5개(소프트 프롬프트 주입은 컨텍스트 비용이 발생하므로 적은 것이 좋음); 경험 라이브러리에 하드 용량 제한은 없지만, 단일 라이브러리는 <500개를 권장합니다(초과 시 타겟 정확도가 떨어지며, 공유 풀로 분산 가능);
타겟 규칙: 유전자 signals_match 히트와 쿼리 단어의 교차점 점수로 순위를 매기며, 임계값 미만이면 전체가 주입되지 않음(타겟이 아닌 주입은 오히려 비용을 증가시킴);
다중 유전자 충돌 시: geneConflicts 가드가 이미 anti_patterns 상호 배타적인 저점수 항목을 자동으로 제거; 여러 개가 남아 있으면 높은 점수 항목 선택; 타겟 항목이 없으면 주입하지 않음, 관련 없는 유전자로 채우지 않음;
본 작업과 관련된 경우 우선 채택; 종료 시 실제로 채택된 항목의 히트 등록(--gene <id>는 id로 주소 지정, 동시성 안전):

node code/evolver-recall.mjs --register-hit --gene <asset_id 또는 gene_id> --note "<작업 한 줄>"

관련 없는 경험을 억지로 적용하지 마십시오; 채택되지 않은 항목은 등록할 필요가 없습니다.

흐름 B: 오류 수정 후 — 경험 축적

EN: Flow B - deposit after fixing a non-obvious failure. Deposit bar (any one): docs/2+ tries needed, environment-specific, counter-intuitive error, or second occurrence. Guided path: draft --error auto-extracts signals + pre-fills AVOID + writes anti_patterns; fill in FIX then --commit. Manual path: distill with explicit signals. strategy MUST be an executable fix (params/commands/encodings) - success summaries are filtered by the repair-signal guard. --shareable only for genes meant for the shared pool. 판단 기준(하나라도 만족하면 축적할 가치 있음):

문제 해결을 위해 문서 확인/시행착오 ≥2회 필요;
본 머신 또는 환경 특성(인코딩, 경로 규칙, 셸 차이, 네트워크 환경)에 의존;
오류 메시지가 직관적이지 않거나 문서 설명과 일치하지 않음;
동일한 함정이 이전 작업에서 두 번째로 발생한 경우. (하나도 만족하지 않는 일반적인 오류는 축적할 필요 없음 — 경험 라이브러리 노이즈 방지.)

권장 경로: 안내식(원시 오류를 붙여넣으면 신호와 '부정 경험'이 자동 추출됨)

# 1) 초안 생성: signals_match 자동 추출 + AVOID 템플릿 미리 채움 + anti_patterns(부정 경험 토큰) 작성
node code/light-cli.mjs draft --error "<원본 오류 텍스트>" --tool <오류가 발생한 도구명> --context "<당시 수행 중인 작업>"

# 2) 초안을 기반으로 FIX 완성 후 저장소에 저장(--strategy가 미리 채워진 플레이스홀더를 덮어씀)
node code/light-cli.mjs draft --error "<원본 오류 텍스트>" \
    --strategy "AVOID: <하지 말아야 할 것> FIX: <구체적인 매개변수/명령/인코딩>" --commit

# 3) 검토(4가지 의미론적 상태 머신은 아래 '검토 상태 머신' 단일 섹션 참조; approve는 자동으로 증거 수집 실행)
node code/light-cli.mjs approve <gene_id>

AVOID/FIX 템플릿 적용 범위(명확히 작성해야 가드가 거부하지 않음):

섹션	작성할 내용	경계
`AVOID:`	하지 말아야 할 것(부정 경험, 위험한 단어 포함 가능 — 그것은 경고)	한두 문장; 성공 요약을 작성하지 마십시오
`FIX:`	매개변수/명령/인코딩까지 구체적인 실행 가능한 수정 방법	반드시 실제로 채워야 함 — 플레이스홀더/재시도 로그/해설은 depositionGate에 의해 거부됨(fail-closed)
`anti_patterns:`	단일 토큰 리터럴(예: `assume-default-utf8`)	충돌 판단은 전체 문자열 매칭 기준; kebab 긴 문장을 작성하지 마십시오
`signals_match:`	불러오기 타겟 신호 단어	쿼리 단어와 교집합이 있어야 불러올 수 있음; 관련 없는 단어를 쌓지 마십시오

대체 경로: 수동 작성식(신호가 이미 명확할 때)

node code/light-cli.mjs distill --category repair --signals bash,exception \
    --strategy "<한 줄 수정 방법; 여러 단계는 세미콜론으로 구분; 매개변수/명령/인코딩까지 구체적으로>" \
    --summary "<함정 한 줄 설명>" [--shareable]

strategy는 실행 가능한 수정 방법(구체적인 매개변수/명령 포함)으로 작성해야 하며, 성공 요약을 작성하지 마십시오 — 불러오기 측에 수정 가드가 있어 성공 요약은 필터링됨(부족함은 있더라도 과유불급);
--shareable은 자신의 유전자가 공유 풀에 들어가길 원할 때만 추가(기본적으로 비공유 = 외부 전송 안 함);
축적 임계값의 실제 데이터(정직한 경계): 프로덕션 실제 세션에서 자동 추출 가능한 '깨끗한 수정 쌍' 밀도는 매우 낮음(실측 distillablePairs=0) — 본 라이브러리의 유전자는 주로 수동/안내식 축적에서 비롯됨.

축적 품질 게이트 depositionGate (0.17.0, fail-closed)

EN: Quality gate at DEPOSITION time (fail-closed): rejects unfilled placeholder / retry-log repetition / narration openings / missing repair-signal words / AVOID-without-FIX. Non-interactive deposits default to quarantined. Full review semantics: the「검토 상태 머신」section below. distill / draft --commit 시 항목별로 검사하며, 유효하지 않은 경우 직접 거부(저장되지 않음):

거부 조건	이유	다음 단계
FIX가 채워지지 않은 플레이스홀더 `<여기에 실행 가능한 수정 방법 작성>`	주입 후 무가치	초안에 실제 수정 방법을 추가한 후 제출
`retry with corrected args` (재시도 로그 재진술)	"재시도 후 해결됨"은 수정 방법이 아님	AVOID(왜 틀렸는지)+FIX(어떻게 할지) 작성
해설로 시작(Now I understand…)	추론 흐름은 실행 불가능	동일
수정 신호 단어 부족	함정과 수정 방법을 설명하는 것처럼 보이지 않음	동일
AVOID만 있고 FIX 없음(반제품)	함정만 있고 수정 방법이 없어 주입 후 무가치(0.22 재검토 실증: 3개의 차단된 deposit이 모두 이 형태)	실행 가능한 수정 방법(매개변수/명령/인코딩) 추가

검토 상태 머신 (단일 사실 출처 · 0.36 수렴)

유전자가 저장소에 들어간 후부터 주입 가능해질 때까지의 모든 검토 의미론은 이 섹션에서만 유지되며, 나머지 문서는 모두 여기를 가리킴(여러 곳에서 표현이 달라지는 것을 방지 — 0.35 평가에서 지적됨). EN: The single source of truth for all review semantics; other docs only point here.

시나리오	기본 동작	덮어쓰기 방법
로컬 대화형 축적(`draft --commit` / `distill`, TTY 있음)	자동 통과	`config --auto-approve off`로 수동 변경; 로컬 축적에만 적용
로컬 비대화형 축적(스크립트/cron/파이프, TTY 없음)	기본 격리(quarantined)	명시적 `--auto-approve`가 있어야 통과
`approve <gene_id>`	자동으로 먼저 증거 수집 — 로컬 4가지 원장(도구 오류/불러오기/주입/역채움) 3단계 출력(강한 증거/약한 컨텍스트/증거 없음), 일치 확인 후 승인	`--skip-evidence`는 알려진 증거 없는 시나리오를 위한 명시적 비상 탈출구(권장하지 않음); 결론이 이후 이벤트에 의해 뒤집힌 경우 격리 상태 유지 및 기록 남김
풀 가져오기 `gene import` / `gene pull`	official 티어 직통(서명 확인); community 기본 격리	`--tier`로 결정

approve가 증거 수집에 묶인 이유: 0.20.3에서 evidence 명령을 만들었지만 "실행해야 한다"는 점에 의존 — 당일 6개를 검토했는데 모두 실행하지 않음. 메커니즘은 반드시 동작 노드에 바인딩되어야 함(T3 철학: 오류 자체가 알림).
상태 원장 review.jsonl은 LWW 추가식이며, approve/quarantine은 양방향으로 되돌릴 수 있음; info의 '대기 중' = 최종 상태가 approved도 quarantined도 아님.
두 계층 품질 게이트와의 관계: depositionGate은 저장소 진입 전에 거부(이전 섹션), 4가지 가드는 불러오기 측에서 필터링(다음 섹션) — 어느 계층에서든 거부되면 주입되지 않음.
로컬 증거가 없는 유전자(공유 풀/다른 머신/시작 팩 출처)는 내용과 출처를 기준으로 검토하며, 승인 시 출처를 명시.

EN: Review-with-evidence (0.20.3): before approve, run evidence <gene_id> to check the four local ledgers for events matching the gene's claimed failure/fix. Approve only when consistent; genes whose conclusions were overturned by later events stay quarantined with an audit note. Genes without local evidence (pool imports / other machines / starter pack) are reviewed on content and source, noted at approval.

유전자 서명 및 출처 (0.21)

EN: Every deposit is signed with this machine's Ed25519 identity (private key 0600, never leaves the machine); pool imports verify signatures - tampered content is REJECTED. Version-by-version details (v2 canonicalization, source attribution, source_kv, decay): docs/advanced.md §Provenance.

축적 시 자동 서명, 풀에 들어갈 때 함께 이동, 가져올 때 서명 확인: 내용이 변조되면 → 가져오기 거부; 서명이 없는 기존 유전자는 그대로 수용(legacy);
개인 키는 머신을 벗어나지 않음; 공개 키는 유전자와 함께 풀에 들어가고 나가며 다른 머신이 서명을 확인할 수 있게 함 — 신뢰 모델은 'keyid로 출처 추적'이지, 중앙 집중식 CA가 아님;
출처 필드는 deposit/역채움 시 자동으로 기록(source_model / source_host / source_kv 압축 체계군); 유전자 유효성은 피드백에 따라 감쇠(시간 반감기 90일 + 부정 압력, 바닥 0.25, 피드백 없으면 감쇠 안 함) — 버전별 상세(v2 정규화 / 정확한 귀속 / 위상 흔적 남기기 / 감쇠 매개변수)는 docs/advanced.md §Provenance에서 확인.

배포 및 배포 (0.23)

EN: Download paths, host integration, pool collaboration, concurrency semantics and scoring; version-by-version detail in docs/advanced.md §Deployment.

다운로드: GitHub Release zip / npm(국내 미러는 FAQ Q7 참조, sha256 검증 포함);
호스트 연동: light-cli.mjs install <claude-code|cursor|codex|agents-md>(--yes로 디스크에 저장); OpenClaw/Hermes는 install-hooks 사용; 트리거 규정은 install-snippet으로 임의의 지시 파일에 작성 가능;
유전자 풀 협업: gene pull --pool <URL|명칭> --tier official [--scene <시나리오>](서명 확인); gene submit --bundle <file>로 관리자에게 반환; 명명된 풀은 ~/.evomap/pools.json에서 확인; 기여 약관은 CONTRIBUTING.md 참조(CC-BY-4.0);
동시성 의미론(3계층, 전체 동작 표는 docs/boundary-and-triggers.md §5 참조): 단일 머신 다중 세션=withLock 파일 잠금; 다중 머신=유전자 풀 Git화(LWW 원장 중재); 다중 호스트는 gene_id로 주소 지정(0.18부터);
불러오기 점수 및 임계값(공개 수치): signals 히트 +3/개 + 본문 토큰 교집합 +1/개 + 로드 밸런싱 바이어스 ±2; 임계값 2점 미만은 주입 안 함(타겟이 아닌 주입은 주입하지 않는 것보다 나쁨, 실측 +36pp); 토큰화=ASCII 토큰(≥3 문자) + 중국어 2자 이항 단어 — 여러 글자의 중국어 구문을 signals에 작성하면 효과 없음(fix-signals로 체험 가능);
세션 펜스(0.27): session open "<작업>"으로 한 번에 T1 불러오기+기장 완료, session close "<결론>"으로 마무리 — 짝이 맞지 않는 open/close는 빌드 게이트에서 거부됨(감사 바인딩);
효과 정량화 및 역채움: report 주간 보고서(L1 활성도/L2 역채움율/L3 재발, --json 기계 판독); recall --record "<결론>"으로 검증 결론 역채움; license verify <token>으로 Ed25519 서명 라이선스 확인;
IO 탄력성 및 오류 코드(0.34): 일시적 오류는 자동 재시도(3회/3초) → 연속 5회 실패 시 서킷 브레이커 10초(IO 복구 시 종료); 모든 실패에는 명명된 오류 코드 [E_USAGE]/[E_ARGS]/[E_GUARD]/[E_NOTFOUND]/[E_INTERNAL] 첨부(0/1/2 종료 코드 유지) — 매개변수 및 전체 표는 docs/advanced.md 참조;
이론적 출처: 이종 검증의 문제 의식은 arXiv:2512.05117에서 비롯됨(자세한 내용은 README 감사 섹션과 docs/research.md 참조); 버전별 상세(출처/별칭 트리거 단어/라이선스/감쇠 매개변수)는 docs/advanced.md §Deployment 참조.

보안: 4중 게이트 (0.16.0)

EN: Four gates: repair-signal guard, narration guard, injection guard (malice; AVOID=warning allowed vs FIX=instruction blocked), redaction gate (privacy, fail-closed off-machine). Per-gate details: docs/security-and-license.md §Gates.

#	게이트	관리 내용	적용 위치
1	수정 가드	진짜 수정 방법이 있는지(실행 가능한 내용이 없으면 → 주입 안 함; 부족함은 있더라도 과유불급)	불러오기
2	서술 가드	해설 흐름인지(해설은 지능체에게 제로 정보, 실측 시 노이즈와 동등 +36pp)	불러오기
3	주입 가드	악성 명령인지(프롬프트 주입 → 주입 안 함; '유전자가 호스트를 역으로 조종하는 것'에 대한 주 방어선)	불러오기(CLI / Pi 확장 브리지 경량판 / 오케스트레이터) + 가져오기 + 내보내기
4	비식별화 게이트	개인 정보 유출 여부(IP/경로/키 → 차단하여 네트워크 밖으로 나가지 않음)	내보내기 + 가져오기

다운그레이드 의미론: 내보내기/가져오기 fail-closed(가드 모듈 누락 시 실행 거부); 불러오기 측은 주입 게이트만 건너뛰고 나머지 세 게이트는 정상 작동(호스트 부트스트랩 경로는 가드 실패로 인해 사용자를 차단하지 않음 — 읽기만 차단하지 않으며, 쓰기는 반드시 closed여야 함).
각 게이트가 구체적으로 무엇을 스캔하는지, 적중 시 동작, 0.31에서 수정된 두 가지 미검출과 회귀 테스트 케이스: docs/security-and-license.md §Gates에서 통일 확인 — 본 문서는 주입 트리거 특성을 반복하지 않으며, 문서 자체가 스캐너에 의해 샘플로 간주되는 것을 방지함(본 저장소에는 이 때문에 발행된 선례가 있음).

기능 경계 빠른 검색 (언제 사용을 기대하지 말아야 할지)

부적용 시나리오 6가지(다중 머신 동일 라이브러리 쓰기 / 100% 함정 회피 보장 / 실시간 동기화 라이브러리 / 일회성 작업 / 권위적인 지식 베이스로 사용 / 아키텍처 간 직접 재사용) 및 정량적 경계(기본 주입 5개, 라이브러리 규모 상한 실측 안 됨, 다중 머신 분산 잠금 없음, Node ≥22)는 통일 docs/boundary-and-triggers.md §1–§2에서 확인. EN: Capability limits ("when NOT to use") and quantitative bounds: docs/boundary-and-triggers.md §1–§2.

언제 알릴지: 5가지 트리거 포인트 (0.16.0의 핵심 설계)

EN: Recall bound to concrete action nodes, never left to memory: T1 task start, T2 before first side-effecting action, T3 on error (the error text IS the query), T4 after fixing, T5 task end (register-hit/negate). Full spec: docs/boundary-and-triggers.md. '스킬을 설치했지만 아무도 호출하지 않음'이 이 프로젝트의 가장 근본적인 실패 모드입니다 — 작성자조차 잊습니다(실측: 관련 유전자가 #1로 불러와질 수 있지만, 실행 전에 불러오기를 실행하지 않아 반복적으로 함정을 밟음). 따라서 '사용자가 기억할 것'을 기대할 수 없으며, 불러오기를 구체적인 동작 노드에 반드시 바인딩해야 합니다.

#	트리거 포인트	시점	명령	연결하지 않으면 어떻게 될까
T1	작업 시작	비사소한 작업을 받고 계획을 세우기 전	`recall --query "<작업>"`	예방 실패: 피해야 할 함정을 그대로 밟음
T2	행동 전	첫 번째 되돌릴 수 없는 동작을 실행하기 직전(파일 쓰기/코드 커밋/배포/외부 인터페이스 호출/데이터 삭제 및 수정); 동일 작업 내 유사 동작은 한 번만 트리거, 이후에는 이번 결론을 재사용	동일 (query=곧 수행할 구체적인 동작, 예: "스크립트로 파일 일괄 변경")	밀착 예방 (선택 사항)
T3	오류 발생 시	도구가 오류를 반환하고, 재시도 준비 전	`recall --error "<오류 원문>"`	가장 아쉬운 경우: 라이브러리에 분명 수정 방법이 있는데, 맹목적으로 재시도함
T4	함정 수정 후	명백하지 않은 함정을 수정했을 때	`draft --error ...`(축적)	경험 손실, 다음 머신이 다시 밟음
T5	작업 종료	마무리	`--register-hit --gene <id>` / `--negate --gene <id>`	측정 불가능, 무효 수정 방법 발견 불가

T3를 별도로 강조(수익은 가장 높지만, 가장 쉽게 간과됨): 유일하게 '사용자가 기억할 필요' 없는 트리거 포인트 — 오류 자체가 알림입니다. 도구가 오류를 반환하고, 재시도를 준비하기 전에 오류 원문을 그대로 쿼리로 사용(스스로 요약하지 마십시오): node code/evolver-recall.mjs --error "<오류 원문>"; 적중 후 수정 방법에 따라 재시도, 여전히 실패 → T4 축적 진행.

전체 트리거 사양은 통일 docs/boundary-and-triggers.md에서 확인 — T2 판단 기준과 3가지 예제, 다중 호스트 동시성 행렬, 트리거 단어↔명령 매핑, 세 가지 호스트 연동 방식, 국내 미러, '설치했으나 효과 없음' 자가 점검을 포함. 본 파일은 위의 핵심 테이블만 유지하며, 두 곳에서 각각 표류하지 않음. 트리거 단어는 호출 힌트일 뿐, 불러오기 매칭 메커니즘이 아닙니다(적중은 signals_match × query-token 타겟에 의존); 작업 시작 시 '비사소한' 것으로 판단되면 T1을 실행하며, 특정 단어 그룹에 일치할 필요는 없습니다.

일반적인 오용 사례 (안티패턴 빠른 검색)

EN: Anti-pattern quick list - each row explains the MECHANISM, not just the symptom. Full 14-item catalog with [A] evidence: docs/common-mistakes.md. Key ones: success-summary strategies are noise (+36pp worse than nothing), model-may-fail traps have unreliable hit rates, token deltas need a no-injection control group (~-22% repeat-execution baseline), error counting must use authoritative flags (isError=true), cold start needs flow-B deposits first. 각 항목에는 '왜 틀렸는지' — 현상이 아닌 메커니즘을 설명하는 내용이 포함됩니다. 전체 목록(추가 항목 포함)은 docs/common-mistakes.md에서 확인하십시오.

잘못된 방법	왜 틀렸는지 (메커니즘)	올바른 방법
`strategy`를 성공 요약으로 작성 ("bash에서 for 루프 사용")	수정 가드가 필터링: 신호 단어 부족 + 실행 불가능 내용 = 주입 안 함; 실측 시 +36pp 노이즈	구체적인 매개변수/명령/인코딩으로 작성 (`AVOID: ... FIX: ...`)
'모델이 실패할 수도 있음' 트랩(`distill --category model-may-fail`)을 일상적으로 사용 (트랩 히트율은 프롬프트 총 길이에 민감)	`model-may-fail` 트랩의 히트율은 프롬프트 길이 변동에 민감하며 3-4% 범위에서 신뢰할 수 없음; 정량화 목적으로만 사용하고 일상적인 경험 축적에는 사용하지 마십시오	일상적인 축적은 `repair` 범주 사용
토큰 델타 분석에 주입 없는 대조군 없음	주입 없는 대조군을 제거하면 반복 실행 기준선이 ~-22% 변동; 대조군 편향의 원인이므로 delta 필드를 보려면 기본값 `--no-injection`을 사용하여 분리	`report --delta` 사용 시 대조군(주입 안 함, `--no-injection`) 유지
오류 수를 계산할 때 `isError` 대신 `error` 필드 사용	`error`에는 오류 외에도 정보 메시지가 포함됨; 공식 `isError=true` 플래그가 권위적임; 오류 카운터는 false positive(정보 메시지를 오류로 착각)를 허용하지 않음	`isError=true`로 필터링된 오류만 계산
첫 번째 사용 시 바로 효과 기대(냉간 시작)	라이브러리가 비어 있으면 어떤 유전자도 불러올 수 없음; 냉간 시작 시 먼저 B 흐름을 실행하여 수동으로 첫 번째 유전자 축적	`T3(오류) → 수정 → T4(축적)` 순서 실행

14개 전체 항목 목록 + 각각에 대한 [A] 실측 증거는 docs/common-mistakes.md에서 확인 — 프로덕션 작업에서 실제 관찰된 데이터를 기반으로 하여 모든 '모범 사례'에 실증적 근거가 있도록 보장합니다.

문서 내비게이션

새 사용자 진입: examples/quickstart.md → docs/overview.md → docs/common-mistakes.md(위의 14개 안티패턴);
상세 안내: docs/advanced.md(배포/출처/운영/성능/공유 풀);
보안 상세: docs/security-and-license.md;
트리거 규격 및 호스트 연동: docs/boundary-and-triggers.md;
프로바이더 설정: docs/providers.md;
FAQ: docs/faq.md(14개 완전한 질문 + Node 적격성 체크리스트);
설정 오류: docs/config-errors.md;
연구 노트: docs/research.md(흐름 C 실험 + 데이터 분석);
기여: CONTRIBUTING.md;
버전 업데이트 로그: CHANGELOG.md.

EN: docs/ dir contains all supplementary docs; this file focuses on quick-start, core flows, security summary & navigation. docs/ 디렉토리에는 모든 보충 문서가 포함되어 있습니다; 이 파일은 빠른 시작, 핵심 흐름, 보안 요약 및 내비게이션에 중점을 둡니다.

Pi × EvoX Loop — 智能体经验继承 Skill

Pi × EvoX Loop — 智能体经验继承 Skill란 무엇인가요?

즐겨 사용하는 AI에게 물어보기

문서