Back to Details

instinct-system

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Instinct System

Instinct系统

One learning system, three tiers. Every signal Claude receives during work — an observed pattern, a user correction, a surprising discovery — routes to exactly one store.
一套学习系统，三个层级。Claude在工作中接收的每一个信号——观察到的模式、用户的修正、意外的发现——都会被精准路由到对应的存储位置。

Core Principles

核心原则

  1. Three tiers, one routing decision — Instincts are unconfirmed hypotheses (
    .claude/instincts.md
    ). Corrections are user-confirmed rules (
    MEMORY.md
    ). Discoveries are insights that explain the world (
    .claude/learning-log.md
    ). Rules prescribe behavior; insights describe it; instincts are rules-in-waiting. Never mix the tiers — a hypothesis in MEMORY.md pollutes permanent knowledge, and a confirmed rule left as an instinct gets forgotten.
  2. Instincts are hypotheses, not rules — An instinct starts as a guess from a single observation and has no authority until confirmed. "One handler uses 
    sealed
    " is an instinct at 0.3; "all 12 handlers use 
    sealed
    " is a rule at 0.9. Confidence (0.3–0.9) drives behavior: note at 0.3, mention at 0.5, follow at 0.7, promote at 0.9.
  3. A user correction is a confirmed instinct at full confidence — When the user corrects you, skip the confirmation cycle entirely. Generalize the lesson, capture it immediately in MEMORY.md with the "why", and confirm what was captured. A correction costs the user 30 seconds today and saves hours across all future sessions — losing one is the most expensive mistake this system can make.
  4. Project-scoped, never global — What holds in one codebase may be wrong in another. Instincts live per-project; transfers between projects go through export/import with confidence decay, never at full confidence.
  5. Review at session start, prune periodically — Read MEMORY.md and load instincts at 0.7+ before writing any code; scan recent log entries for the working area. Knowledge captured but never reviewed is wasted effort. Audit all three stores when they bloat — stale instincts, duplicate rules, and unreviewed logs defeat the purpose.
  1. 三个层级，一次路由决策 —— Instincts是未确认的假设（存储于
    .claude/instincts.md
    ）。修正内容是用户确认的规则（存储于
    MEMORY.md
    ）。发现内容是用于解释事物规律的洞察（存储于
    .claude/learning-log.md
    ）。规则规定行为；洞察描述规律；Instincts是待确认的规则。切勿混淆层级——将假设放入MEMORY.md会污染永久知识，而将已确认的规则留在Instincts中则会被遗忘。
  2. Instincts是假设，而非规则 —— Instinct始于单次观察得出的猜测，在被确认前不具备权威性。"某个处理器使用
    sealed
    "是置信度为0.3的Instinct；"所有12个处理器都使用
    sealed
    "是置信度为0.9的规则。置信度（0.3–0.9）决定行为：0.3时仅记录，0.5时提及，0.7时遵循，0.9时升级为规则。
  3. 用户修正即置信度拉满的已确认Instinct —— 当用户修正你时，直接跳过确认流程。将经验归纳泛化，立即捕获到MEMORY.md中并注明“原因”，同时确认已捕获的内容。一次修正会花费用户当前30秒时间，但能在未来所有会话中节省数小时——丢失一次修正是本系统可能犯下的最昂贵错误。
  4. 项目专属，绝非全局通用 —— 在一个代码库中成立的规则，在另一个代码库中可能不适用。Instincts按项目存储；项目间的迁移需通过导出/导入完成，且置信度会衰减，绝不会以满置信度直接迁移。
  5. 会话开始时回顾，定期清理 —— 在编写任何代码前，先阅读MEMORY.md并加载置信度0.7及以上的Instincts；扫描工作领域的近期日志条目。已捕获但从未回顾的知识是无用功。当三个存储库膨胀时，需全面审计——过时的Instincts、重复的规则和未回顾的日志会违背本系统的初衷。

Patterns

模式

Tier Routing

层级路由

SignalDestinationLifespan
Pattern observed, not yet confirmed ("I think they always...")
.claude/instincts.md
at 0.3		Until promoted or discarded
User correction ("no, use X", "don't do that again", "remember this")
MEMORY.md
immediately, generalized		Permanent until proven wrong
Instinct reaching 0.9 confidencePromote to 
MEMORY.md
, remove from instincts		Permanent
Non-obvious discovery (bug root cause, gotcha, workaround, perf finding)
.claude/learning-log.md
3–6 months, then archive or promote
Same gotcha logged 3+ timesPromote to 
MEMORY.md
as a preventive rule		Permanent
Session state (done/pending)Handoff via wrap-up — not this systemUntil next session
信号类型存储位置生命周期
观察到的未确认模式（"我认为他们总是..."）
.claude/instincts.md
，置信度0.3		直至升级或丢弃
用户修正（"不，用X"、"别再那么做了"、"记住这个"）立即存入
MEMORY.md
，已泛化		永久保存，除非被证明错误
置信度达到0.9的Instinct升级至
MEMORY.md
，从Instincts中移除		永久保存
非显而易见的发现（bug根源、陷阱、临时解决方案、性能发现）
.claude/learning-log.md
3–6个月，之后归档或升级
同一陷阱被记录3次及以上升级至
MEMORY.md
作为预防性规则		永久保存
会话状态（已完成/待处理）通过收尾环节交接——不属于本系统直至下一次会话

Instinct Lifecycle (Observe-Hypothesize-Confirm)

Instinct生命周期（观察-假设-确认）

1. OBSERVE     — "This handler is internal sealed class. Convention?"
2. HYPOTHESIZE — Write to .claude/instincts.md at confidence 0.3:
                 - Use `sealed` on handler classes | confidence: 0.3 | seen: 1 | last: 2026-06-12
3. SEEK        — Actively check 2-3 related files (find_symbol, get_public_api).
                 Passive observation is not enough.
4. ADJUST      — Confirmed: raise per the adjustment track.
                 Contradicted: halve confidence, note the exception.
                 Mixed: hold steady, note the split.
5. PROMOTE     — At 0.9, present evidence and offer promotion to MEMORY.md.
1. OBSERVE     — "这个处理器是内部sealed类。是约定吗？"
2. HYPOTHESIZE — 写入.claude/instincts.md，置信度0.3:
                 - 处理器类使用`sealed` | 置信度: 0.3 | 已观察: 1 | 最后更新: 2026-06-12
3. SEEK        — 主动检查2-3个相关文件（find_symbol, get_public_api）。
                 被动观察远远不够。
4. ADJUST      — 确认：按调整规则提升置信度。
                 矛盾：将置信度减半，记录例外情况。
                 混合：保持置信度不变，记录分歧。
5. PROMOTE     — 置信度达0.9时，呈现证据并提议升级至MEMORY.md。

Instinct Storage Format

Instinct存储格式

.claude/instincts.md
, grouped by category with structured metadata:
markdown
undefined
.claude/instincts.md
，按类别分组并附带结构化元数据：
markdown
undefined

Project Instincts

项目Instincts

Code Style [0.7]

代码风格 [0.7]

  • Use 
    sealed
    on all handler classes | confidence: 0.8 | seen: 5 | last: 2026-06-12
  • Prefix private fields with underscore | confidence: 0.5 | seen: 2 | last: 2026-06-10
  • 所有处理器类使用
    sealed
    | 置信度: 0.8 | 已观察: 5 | 最后更新: 2026-06-12
  • 私有字段以下划线为前缀 | 置信度: 0.5 | 已观察: 2 | 最后更新: 2026-06-10

Architecture [0.7]

架构 [0.7]

  • Feature folders use singular names | confidence: 0.7 | seen: 4 | last: 2026-06-12

Category header `[0.7]` = average confidence. Standard categories: Code Style, Architecture, Naming, Testing, Data Access, API Design, Configuration, Performance, Tooling.
  • 功能文件夹使用单数名称 | 置信度: 0.7 | 已观察: 4 | 最后更新: 2026-06-12

类别头部的`[0.7]` = 平均置信度。标准类别：代码风格、架构、命名、测试、数据访问、API设计、配置、性能、工具。

Confidence Adjustment Rules

置信度调整规则

No ad-hoc scoring. Follow this track precisely:
CONFIRMATION:  1st observation → 0.3 | 2nd → 0.5 | 3rd → 0.7 | 4th → 0.8
               5th+ with zero contradictions → 0.9 (promotion candidate)

CONTRADICTION: Any contradiction → halve current confidence (0.7 → 0.35)
               Two in a row → 0.1 (effectively dead)

USER OVERRIDE: Explicit confirm → 0.8 | Explicit correct → 0.0 (remove,
               capture in MEMORY.md instead) | "Sometimes" → cap at 0.5

STALENESS:     No observations for 10+ sessions → flag for review
               Contradicted, unreconfirmed for 5 sessions → remove
禁止临时评分。严格遵循以下规则：
确认： 第1次观察 → 0.3 | 第2次 → 0.5 | 第3次 → 0.7 | 第4次 → 0.8
       第5次及以上无矛盾 → 0.9（升级候选）

矛盾： 任何矛盾 → 当前置信度减半（0.7 → 0.35）
       连续两次矛盾 → 0.1（实际已失效）

用户覆盖： 明确确认 → 0.8 | 明确修正 → 0.0（移除，
           转而存入MEMORY.md） | "有时" → 置信度上限0.5

过时： 10次及以上会话未观察到 → 标记待回顾
       存在矛盾且5次会话未确认 → 移除

Acting on Instincts by Confidence

按置信度执行Instinct

0.0–0.2 → IGNORE  — insufficient evidence, do not mention
0.3–0.4 → NOTE    — record internally, do not apply
0.5–0.6 → MENTION — "This project may use [pattern]. Follow it?"
0.7–0.8 → FOLLOW  — apply by default, mention on first use
0.9     → PROMOTE — offer to add to MEMORY.md as a permanent rule
Never silently apply an instinct below 0.7.
0.0–0.2 → 忽略  — 证据不足，无需提及
0.3–0.4 → 记录  — 内部记录，不应用
0.5–0.6 → 提及  — "此项目可能使用[模式]。是否遵循？"
0.7–0.8 → 遵循  — 默认应用，首次使用时提及
0.9     → 升级  — 提议添加至MEMORY.md作为永久规则
切勿静默应用置信度低于0.7的Instinct。

Correction Capture Flow (Tier 2)

修正捕获流程（第二层）

When the user corrects your output ("no, use X instead", "we don't do it that way", "always/never do X", "remember this"):
1. DETECT      — Recognize the correction signal.
2. ACKNOWLEDGE — "Got it — HybridCache instead of IMemoryCache."
3. GENERALIZE  — Specific: "Don't use IMemoryCache in the Orders endpoint"
                 General:  "Always use HybridCache over IMemoryCache —
                            stampede protection + L1/L2 out of the box."
                 Ask: is this specific to this file? This layer? What's the
                 underlying principle? Store the broadest correct statement.
4. CHECK       — Scan MEMORY.md for overlap. Update an existing rule rather
                 than adding a near-duplicate.
5. STORE       — Write under the right category, one line, rationale after
                 the dash. If a matching instinct exists, remove it — it
                 just graduated.
6. CONFIRM     — "Added to Memory > Data Access: HybridCache over IMemoryCache."
MEMORY.md format — same categories as instincts, one actionable rule per line:
markdown
undefined
当用户修正你的输出时（"不，改用X"、"我们不那么做"、"永远/绝不做X"、"记住这个"）：
1. DETECT      — 识别修正信号。
2. ACKNOWLEDGE — "明白了——用HybridCache替代IMemoryCache。"
3. GENERALIZE  — 具体表述："不要在Orders端点使用IMemoryCache"
                 泛化表述："始终使用HybridCache而非IMemoryCache——
                            内置缓存击穿防护 + L1/L2缓存。"
                 询问：这仅适用于此文件？此层级？底层原则是什么？存储最宽泛的正确表述。
4. CHECK       — 扫描MEMORY.md是否存在重叠内容。更新现有规则而非添加近乎重复的内容。
5. STORE       — 写入对应类别，单行格式，理由写在破折号后。如果存在匹配的Instinct，将其移除——它已升级为规则。
6. CONFIRM     — "已添加至Memory > 数据访问：HybridCache优先于IMemoryCache。"
MEMORY.md格式 —— 与Instincts使用相同类别，每行一条可执行规则：
markdown
undefined

Data Access

数据访问

  • Always use HybridCache over IMemoryCache — stampede protection + L1/L2
  • Never use repository pattern over EF Core — use DbContext directly
undefined
  • 始终使用HybridCache而非IMemoryCache — 缓存击穿防护 + L1/L2缓存
  • 绝不在EF Core之上使用仓储模式 — 直接使用DbContext
undefined

Discovery Logging (Tier 3)

发现记录（第三层）

Log organic findings to 
.claude/learning-log.md
the moment they occur — a 2-line entry written immediately beats a paragraph reconstructed later. Entry format:
markdown
undefined
在发现的瞬间就将自主发现的内容记录到
.claude/learning-log.md
——立即写下的两行条目胜过事后重构的段落。条目格式：
markdown
undefined

2026-06-12 | Gotcha | MassTransit Consumer Registration Order Matters

2026-06-12 | 陷阱 | MassTransit消费者注册顺序至关重要

Multiple consumers for one message type run in registration order; if the first throws, the rest are skipped. Caused missed audit events. Files: 
src/Shared/Extensions/MassTransitConfig.cs:15-30
Resolution: Independent consumer endpoints or the retry filter.

Log when (and only when) you hit one of these triggers:
Bug Root Cause — the cause was NOT where the error appeared Architecture Decision — discovered WHY something is built a certain way Gotcha — framework/library behaved surprisingly Performance Discovery — unexpected perf behavior, with the measurement Pattern Found — reusable codebase pattern worth remembering External Service — third-party API behaves differently than documented

Those six trigger names are also the category vocabulary — use them verbatim in entries. Routine changes with nothing surprising do not get logged.
同一消息类型的多个消费者按注册顺序运行；如果第一个抛出异常，其余的会被跳过。导致审计事件丢失。 文件: 
src/Shared/Extensions/MassTransitConfig.cs:15-30
解决方案: 独立消费者端点或重试过滤器。

仅在触发以下场景时记录：
Bug根源 — 原因并非出现在错误提示的位置 架构决策 — 发现事物以某种方式构建的原因 陷阱 — 框架/库的行为出乎意料 性能发现 — 意外的性能表现及相关测量值 模式发现 — 值得记住的可复用代码库模式 外部服务 — 第三方API行为与文档不符

这六个触发词也是分类词汇——在条目中严格使用原文。常规变更且无意外内容无需记录。

Session-Start Loading

会话开始加载流程

1. Read MEMORY.md — apply rules proactively, don't wait to be reminded
2. Read .claude/instincts.md — load 0.7+ as defaults, note 0.5–0.6
3. Scan recent learning-log entries for the area you're working in
4. Flag stale instincts (10+ sessions without observation) for review
1. 读取MEMORY.md — 主动应用规则，不要等待提醒
2. 读取.claude/instincts.md — 加载置信度0.7及以上的内容作为默认值，标记置信度0.5–0.6的内容
3. 扫描工作领域的近期学习日志条目
4. 标记过时的Instincts（10次及以上会话未观察到）待回顾

Modes

模式

Three operations on the instinct store, invoked by name or trigger phrase.
对Instinct存储库的三种操作，通过名称或触发短语调用。

Status ("show instincts", "what have you learned", "list instincts")

状态查看（"show instincts"、"what have you learned"、"list instincts"）

  1. Read 
    .claude/instincts.md
    ; parse each entry's metadata.
  2. Sort by confidence descending, group by category, render as a table: instinct | confidence | category | status (new / stable / reinforced / decaying / promotion candidate).
  3. Summarize health: total count, average confidence, recently reinforced vs decaying entries, any conflicting instincts.
  1. 读取
    .claude/instincts.md
    ；解析每个条目的元数据。
  2. 按置信度降序排序，按类别分组，以表格形式呈现： instinct | 置信度 | 类别 | 状态（新建 / 稳定 / 强化 / 衰减 / 升级候选）。
  3. 总结健康状况：总数、平均置信度、近期强化与衰减条目数量、是否存在冲突的Instincts。

Export ("export instincts", "share instincts")

导出（"export instincts"、"share instincts"）

  1. Read 
    .claude/instincts.md
    ; filter to confidence > 0.7 (threshold configurable).
  2. Strip project-specific context (file paths, line numbers) while preserving the pattern itself.
  3. Write to 
    .claude/instincts-export.md
    with portable metadata.
  4. Report what was exported and what was skipped (below threshold), with the output path.
  1. 读取
    .claude/instincts.md
    ；筛选置信度>0.7的内容（阈值可配置）。
  2. 移除项目特定上下文（文件路径、行号），保留模式本身。
  3. 写入
    .claude/instincts-export.md
    并附带可移植元数据。
  4. 报告导出内容和跳过内容（低于阈值），以及输出路径。

Import ("import instincts", "load instincts from")

导入（"import instincts"、"load instincts from"）

  1. Read the export file (user-provided path or 
    .claude/instincts-export.md
    ) and the current 
    .claude/instincts.md
    .
  2. Merge each imported instinct:
    • No local match — add with confidence decayed by 0.2 (0.9 → 0.7); never import above 0.7. Mark 
      source: imported from [project]
      .
    • Matching instinct exists — keep the higher confidence, mark reinforced.
    • Conflicting instinct exists — present both to the user for resolution; do not auto-overwrite local evidence.
  3. Write the merged result and report imported / merged / conflicts. Every project must confirm imported patterns locally.
  1. 读取导出文件（用户提供的路径或
    .claude/instincts-export.md
    ）和当前的
    .claude/instincts.md
    。
  2. 合并每个导入的Instinct：
    • 无本地匹配 — 添加时置信度衰减0.2（0.9 → 0.7）；导入置信度绝不超过0.7。标记
      来源: 从[项目]导入
      。
    • 存在匹配的Instinct — 保留较高的置信度，标记为已强化。
    • 存在冲突的Instinct — 将两者呈现给用户以解决冲突；切勿自动覆盖本地证据。
  3. 写入合并结果并报告导入/合并/冲突情况。每个项目必须在本地确认导入的模式。

Anti-patterns

反模式

Over-Eager Pattern Recognition

过度急切的模式识别

undefined
undefined

BAD — first observation treated as a rule

错误 — 首次观察即视为规则

Reads one handler "This project always uses internal sealed class." Generates 5 handlers that contradict 8 of 9 existing ones
读取一个处理器 "此项目始终使用内部sealed类。" 生成5个与9个现有处理器中的8个相矛盾的处理器

GOOD — hypothesis at 0.3, then active confirmation

正确 — 以0.3置信度创建假设，然后主动确认

"Noticed internal sealed in CreateOrderHandler. Instinct at 0.3. Checking 3 more handlers..." All public → "Disconfirmed. Discarding."
undefined
"注意到CreateOrderHandler中使用了内部sealed类。Instinct置信度0.3。 正在检查另外3个处理器..." 全部为公共类 → "已否定。已丢弃。"
undefined

Fixing Without Capturing

仅修正不捕获

undefined
undefined

BAD — correction applied, lesson lost

错误 — 应用了修正，但丢失了经验

User: "No, we use HybridCache here" Claude: "Fixed." Next session: same mistake
用户："不，我们在这里用HybridCache" Claude："已修正。" 下一次会话：重复相同错误

GOOD — fix AND capture

正确 — 修正并捕获

Claude: "Fixed. Added to Memory > Data Access: Always use HybridCache over IMemoryCache."
undefined
Claude："已修正。已添加至Memory > 数据访问： 始终使用HybridCache而非IMemoryCache。"
undefined

Logging Everything

记录所有内容

undefined
undefined

BAD — noise entry

错误 — 无效条目

2026-06-12 | Pattern Found | Used Primary Constructors

2026-06-12 | 模式发现 | 使用了主构造函数

GOOD — only the non-obvious earns an entry

正确 — 仅记录非显而易见的内容

2026-06-12 | Gotcha | Primary Constructor Params Captured as Fields

2026-06-12 | 陷阱 | 主构造函数参数被捕获为字段

Declaring an explicit field with the same name warns but compiles — and the two can silently diverge.
undefined
声明同名的显式字段会发出警告但仍可编译—— 且两者可能悄然偏离。
undefined

Write-Only Stores

只写存储库

undefined
undefined

BAD — 40 instincts at 0.3 from 3 months ago; MEMORY.md at 200 lines

错误 — 3个月前的40个置信度0.3的Instincts；MEMORY.md有200行

with duplicates; 500-line log nobody reads
包含重复内容；500行无人阅读的日志

GOOD — periodic audit: remove instincts below 0.2 or stale 10+

正确 — 定期审计：移除置信度低于0.2或过时10次+

sessions; merge/prune MEMORY.md past 50 rules; every ~20 log entries, promote recurring findings and archive the stale. Keep instincts under 50 active entries.
undefined
会话的Instincts；合并/清理超过50条规则的MEMORY.md；每约20条日志条目， 将重复出现的发现升级为规则并归档过时内容。保持活跃Instincts数量在50以内。
undefined

Decision Guide

决策指南

ScenarioAction
First time seeing a patternInstinct at 0.3, check 2-3 related files
Pattern seen 3+ times, no contradictionsRaise to 0.7, follow by default
Pattern contradictedHalve confidence, note the exception
User says "we always do X"Instinct at 0.8 (user confirmation)
User corrects your codeGeneralize → MEMORY.md immediately; drop any matching instinct
User says "remember this" / "always/never"Capture in MEMORY.md as stated, generalized
Same correction given twiceHigh priority — the rule wasn't captured or reviewed
Correction about a one-time taskDon't store — only reusable patterns
User asks to forget a ruleRemove from MEMORY.md immediately
Non-obvious bug, gotcha, workaround, perf surpriseLog to learning-log with category + files
Same gotcha logged 3+ timesPromote to MEMORY.md as a preventive rule
Instinct at 0.9Present evidence, offer promotion to MEMORY.md
User partially confirms ("only for commands")Narrow scope, reset to 0.5, re-confirm
Sharing patterns with another projectExport at 0.7+, import with 0.2 decay
Conflict during importPresent both to the user; never auto-overwrite
Any store bloats (50+ entries/rules)Audit: prune dead, merge duplicates, promote mature
Starting a sessionLoad MEMORY.md, instincts 0.7+, recent log entries
场景操作
首次看到某模式创建置信度0.3的Instinct，检查2-3个相关文件
模式被观察3次及以上，无矛盾提升至0.7，默认遵循
模式被否定置信度减半，记录例外情况
用户说"我们总是做X"创建置信度0.8的Instinct（用户确认）
用户修正你的代码泛化 → 立即存入MEMORY.md；删除任何匹配的Instinct
用户说"记住这个" / "永远/绝不"按表述捕获到MEMORY.md，已泛化
同一修正被给出两次高优先级——规则未被捕获或未被回顾
关于一次性任务的修正不存储——仅存储可复用模式
用户要求忘记某规则立即从MEMORY.md移除
非显而易见的bug、陷阱、临时解决方案、性能意外按类别+文件记录到学习日志
同一陷阱被记录3次及以上升级至MEMORY.md作为预防性规则
Instinct置信度达0.9呈现证据，提议升级至MEMORY.md
用户部分确认（"仅适用于命令"）缩小范围，重置至0.5，重新确认
与其他项目共享模式导出置信度0.7及以上的内容，导入时置信度衰减0.2
导入时存在冲突将两者呈现给用户；切勿自动覆盖
任一存储库膨胀（50+条目/规则）审计：清理无效内容、合并重复内容、升级成熟内容
会话开始加载MEMORY.md、置信度0.7及以上的Instincts、近期日志条目

Related

相关技能

  • convention-learner
    — detects codebase conventions in bulk; feed its findings in as instincts
  • wrap-up
    — end-of-session ritual; routes session learnings into the correct tier of this system
  • convention-learner
    — 批量检测代码库约定；将其发现结果作为Instincts导入
  • wrap-up
    — 会话收尾流程；将会话中的学习内容路由到本系统的对应层级