Mandatory: AI Coding Discipline / AI编程纪律（每次对话强制激活）

Mandatory rule. Every coding session executes three-layer discipline: Pre-Gates → 6 Principles → 3 Traps. V2.7 adds Multi-Stack Detection + Progressive L1/L2/L3 Activation. 强制纪律。每次编码会话必须执行三层体系：前置门 → 六大原则 → 三大陷阱。V2.7 新增多技术栈陷阱检测 + 按改动大小分层激活。

Usage Rules / 使用规则

Must execute when any of the following is true / 以下任一条件满足时必须执行：

• User asks to modify code / 用户要求修改代码
• User reports a bug / 用户报告 Bug
• User requests a new feature / 用户要求新功能
• Code review / refactoring / 代码审查或重构

Layer 1: Pre-Gates / 第一层：前置门（Pre-Code — Must Pass Before Writing Any Code / 动手前必须通过，不通不许写代码）

Gate 1: Three Questions / 门1：三问三答（Patch Self-Check / 补丁自检）

Before proposing any change, answer these three questions (all three required): / 提出修改方案前必须回答三个问题（缺一不可）：

Q1: Have I traced the full call chain? / 我追踪了完整调用链吗？
  → List every node: user entry → API endpoint → data layer → rendering
  → 列出每个节点：用户入口 → 服务端端点 → AI调用 → 前端渲染
  → Write down actual file+function names for each node, don't just say "I checked"
  → 写清文件+函数名，不只是口头说"我看过了"

Q2: Have I confirmed all branch paths? / 我确认了所有分支路径吗？
  → List all paths: different views / environments / user types / platforms
  → 列出所有路径
  → Mark each: "✅ confirmed unaffected" or "🔧 needs sync change"
  → 每一行标注"✅确认不受影响"或"🔧需要同步修改"

Q3: Is my fix an architecture-level unified fix, or a single-path patch? / 修复是架构层面统一修复还是单路径补丁？
  → If only one path was changed → first answer "why can't we unify" before proceeding
  → 如果只改了一个路径 → 先回答"为什么不能统一修复"再动手
  → If the answer is weak → stop and rethink, don't continue
  → 如果答案牵强 → 停下来重新思考，不要继续

Violate any question → the change is invalid, must roll back and restart. / 违反任一条 → 修改视为无效，必须回退重来。

Self-check pass indicator: explicitly output the three answers (short is fine, but must be verifiable). / 自查通过标志：在回复中显式输出三问三答（不用太长，但必须可验证）。

Gate 2: Repeat Bug Cap / 门2：重复Bug上限

Rule: If the same bug has been fixed 2 times and still broken,
      the 3rd action MUST be web search, NOT a 3rd code fix.
规则：同一个Bug改了2次还修不好时，第3次行动必须是上网搜索，不是改第3版代码。

Search strategy / 搜索策略:
1. "[Framework] + [symptom keywords]" (e.g. "React useEffect infinite loop")
2. GitHub Issues (framework official repo)
3. StackOverflow / community forums
4. Try 3 different keyword combinations / 关键词试3组不同组合

Consequences of ignoring / 违反后果:
- 3 fixes = wasted time / 浪费时间
- 4 fixes = introduces new bugs / 引入新Bug
- 5 fixes = project quality collapses / 项目质量崩塌

Gate 3: File Size Decision / 门3：空间决策（300-line Redline + New Feature = New File / 300行红线 + 新功能开新文件）

Before touching any file, check / 动手前判断:
1. Target file current line count > 300? / 目标文件当前超过300行？
   → YES: split first, then modify (never append to large files)
   → 是：先拆分再修改，不往大文件追加
   → Note / 注：🍞 breadcrumb headers (~15-20 lines) do NOT count toward 300 / 🍞 面包屑头部不计入300行上限
2. Is this a new feature or modifying existing? / 这是新增功能还是修改现有？
   → New feature: MUST create new file/module / 新增功能：必须新建文件/模块
   → Modify existing: consider splitting first if file is large / 修改现有：优先考虑先拆分再修改

Exemptions / 豁免:
  - Pure config/declaration/boilerplate: relax to 500 lines / 纯配置/声明/框架代码：可放宽至500行
  - Highly cohesive algorithms (state machines, compiler cores): relax to 400 lines / 高度内聚算法：可至400行
  - Auto-generated code: don't count / 框架自动生成代码：不计入
  - 🍞 Breadcrumb headers (metadata): don't count / 🍞 面包屑头部（元数据）：不计入

Post-change auto-check (self-check rule 29): after modifying a file, if functional code still > 300 lines → ⚠️ warn suggest split
改后自检强制检查（规则 29）：改后自检时，若改动后功能代码仍超 300 行 → ⚠️ 警告建议拆分

Layer 2: Six Principles / 第二层：六大原则（While Coding — Follow Each One / 写码时逐条遵守）

Principle 0: Breadcrumb Pre-Scan 🍞 / 原则0：面包屑预扫描

Breadcrumbs are the AI's project map. Before modifying any file, scan its 🍞 header to understand what else depends on it. 面包屑是AI的"项目地图"。改文件前先扫描🍞头部，了解改了这里会影响谁。

When opening any file for modification / 打开文件准备修改时:

1. Scan for 🍞 breadcrumb block: search for 🍞 AI Breadcrumb in file header / 搜索文件头部🍞导航块
2. If found → parse the breadcrumbs / 解析面包屑:
   • @COUPLED entries → these files must be checked/updated together / 联动文件，必须同步检查
   • 📖 entries → these docs contain related design details → read them / 关联设计文档，需要读
   • @GOTCHA entries → known traps in this code → avoid them / 已知陷阱，避开
   • @BUGFIX entries → historical bugs fixed here → don't regress / 历史修复记录，别回退
3. If NOT found → 🚨 DO NOT modify code yet! Seed breadcrumbs first (30 seconds max): / 禁止直接改代码！先播种面包屑： a. Search linked files / 搜联动文件: search_content for import/require of this file in the project → write @COUPLED b. Search design docs / 搜设计文档: search_content in dev docs for this file name or module name → write 📖, read key decision docs if found c. Check git history / 查历史Bug: git log --oneline -10 <this file> → recent bug fixes → write @BUGFIX d. After completing a-c, insert the 🍞 header block (format below), then proceed with the code change / 完成以上三步后插入🍞头部，再改代码
4. Use parsed breadcrumbs to expand change scope: add @COUPLED files to your "must check" list before making changes / 把联动文件加入检查清单

Breadcrumb standard format / 🍞 面包屑标准格式 (design principle: AI understands at a glance, no external docs needed / AI一眼就能理解，不需要读任何外部文档):

/*
 * ─── 🍞 AI Breadcrumb Navigation ──────────────────
 * Tag meanings: @COUPLED=linked files @GOTCHA=gotcha @BUGFIX=bug fix @MAGIC=magic number
 *              @DEPENDS=external dependency @ASSUME=assumption @TODO=todo @WHY=design rationale
 *              @PERF=performance @CONTRACT=interface contract 📖=dev doc reference
 * 
 * Breadcrumbs (changing this affects):
 *   @COUPLED sync needed: fileA.js#L200, fileB.html
 *   📖 see: docs/architecture/tool-registration.md
 *   @BUGFIX 2026-07-06: reason, fix: solution
 * ──────────────────────────────────────────────────
 */

Why this format AI-readable without external docs / 为什么这个格式 AI 能理解（无需外部文档）:

• 🍞 emoji = visual anchor, AI can grep /🍞/ to locate instantly / 视觉锚点，一秒定位
• Tag meanings line = inline cheat sheet, no need to read ANCHOR_SPEC.md / 内嵌速查手册
• @COUPLED sync needed: file1, file2 = tells AI exactly what to change together / 直接告诉 AI 改哪里
• 📖 see: doc path = entry point to detailed design docs / 设计文档入口
• @BUGFIX date:reason, fix:solution = don't regress / 别回退

Key principles / 关键原则:

• Breadcrumbs are alive — update with every change, not write-once-forever / 面包屑是活的，每次改动都要更新
• Breadcrumbs are specific — @COUPLED must specify file paths, not vague "all frontend files" / 必须写具体路径
• Breadcrumbs are self-documenting — the tag glossary ensures even AI without this Skill loaded can understand / 自解释的
• Don't aim for massive one-time annotation — seed as you go / 改代码即播种

Principle 1: Think First / 原则1：先思考

Don't code from memory. Read files to confirm current state before acting.
Understand WHY the code looks like this before deciding HOW to change it.
Define change scope beforehand — don't expand while coding.

改代码前必须读文件确认现状，不准凭记忆盲改。
先理解为什么代码长这样，再决定怎么改。
修改范围必须事前想清楚，不准边改边扩大范围。

Intent Anchor Pre-Judgment / 意图锚点预判（before writing code, plan what breadcrumb tags you'll need / 写码前预判需要什么标签）:

When reading the target file, scan existing anchors and pre-plan new ones / 读文件时扫锚点并预判:

□ Multiple design choices? → Prepare @WHY chose-A-not-B: reason / 方案有多个选择？→ @WHY
□ Hardcoded business numbers/constants? → Prepare @MAGIC value=meaning, sync with [file] / 硬编码了业务数字？→ @MAGIC
□ Change affects other files? → Prepare @COUPLED sync needed: [file list] / 改动影响其他文件？→ @COUPLED
□ Depends on external system quirks? → Prepare @DEPENDS [system]'s [behavior], must [action] / 依赖外部系统怪异行为？→ @DEPENDS
□ Depends on data format assumptions? → Prepare @ASSUME [assumption], if [condition changes] adjust [logic] / 依赖数据格式假设？→ @ASSUME
□ Temporary workaround? → Prepare @TODO [date] [planned solution] / 临时方案？→ @TODO
□ Fixing a bug? → Prepare @BUGFIX [date]:[cause], fix:[solution], test:[entry] / 修Bug？→ @BUGFIX
□ Performance-sensitive but intentionally not optimized? → Prepare @PERF [why not optimize] / 性能敏感但故意不优化？→ @PERF
□ Design intent too complex for inline comment? → Prepare 📖 [doc path] / 代码写不下设计意图？→ 📖

Don't wait until self-check to add these — by then you've already forgotten the design rationale.
不要等到自检时才补——那时已经忘了设计理由。

Principle 2: Subtraction First / 原则2：做减法优先

When fixing bugs, always ask first: can this be solved by DELETING code?
A bug fixable by removing 3 lines should NEVER add even 1 line of patch.
Fight the LLM's natural instinct to "add code" — code growth is entropy,
good fixes should be entropy reduction.

修Bug时优先问：能不能通过删除代码来解决？
能删3行解决的Bug，绝对不加1行补丁。
对抗LLM天然的"堆代码"本能——代码量增长是熵增，好的修复应该是熵减。

Anti-pattern / 反例:
- ❌ Add an if-branch for a special case (piling code) / 加if分支处理特殊情况
- ✅ Remove the redundant logic that created the special case (subtraction) / 删掉导致特殊情况的冗余逻辑

Self-check: Is the net line count (added - deleted) positive or negative?
If positive, ask: are these added lines truly impossible to delete?
自检：本次改动的净行数是正还是负？如果为正，这些新增代码真的不可删除吗？

Principle 3: Keep It Simple / 原则3：保持简单

Minimize change scope. Never touch unrelated code.
Don't introduce unnecessary abstraction layers.
Keep code readable, maintainable, rollbackable.

最小化改动范围，无关代码一律不动。
不引入不必要的抽象层。
保持代码可读、可维护、可回滚。

Principle 4: Precise Modification / 原则4：精准修改

Only change target code. Don't "optimize" unrelated modules on the side.
Confirm impact scope before modifying, confirm only target files changed after.
Must go through Pre-Gate 1 (Three Questions) to confirm all branch paths.

只改目标代码，不顺手"优化"无关模块。
修改前确认影响范围，改后确认只动了目标文件。
必须走前置门1（三问三答）确认所有分支路径。

Principle 5: Goal-Driven / 原则5：目标驱动

Code must run after changes. Feature must be a closed loop.
Leave no half-finished work, no "I'll fix it later" traps.
Modification complete → verify immediately → confirm closure.

改完代码必须能跑，功能闭环。
不遗留半成品、不留下"回头再弄"的坑。
修改完成 → 立即验证 → 确认闭环。

Layer 3: Three Traps / 第三层：三大陷阱（Must Avoid While Coding / 写码时强制避开）

Trap A: Numeric Values Cannot Use || for Null Check / 陷阱A：数值不可用 || 判空

// ❌ Wrong / 错误: 0 is treated as falsy / 0被当作falsy
const count = userInput || defaultValue;

// ✅ Correct / 正确: only check null/undefined / 只判null/undefined
const count = userInput ?? defaultValue;
// Or for wider compatibility / 或兼容旧版:
const count = userInput != null ? userInput : defaultValue;

Trap B: <select> Must Have Placeholder <option> / 陷阱B：<select> 必须加占位 <option>

<!-- ✅ Correct: default non-submittable placeholder / 有默认不可提交的占位项 -->
<select>
  <option value="" disabled selected>Please select... / 请选择...</option>
  <option value="a">Option A</option>
</select>

Trap C: POST upsert UPDATE Branch Must Not Hardcode Fields / 陷阱C：POST upsert 更新分支不可硬编码字段

POST upsert interface's update logic MUST dynamically read field names,
never hardcode specific fields.
Schema changes over time — hardcoded fields cause new fields to be lost.

POST upsert 接口的更新逻辑必须动态获取字段名，不可硬编码具体字段。
因为schema会变，硬编码字段会导致新字段丢失。

Layer 4: Multi-Stack Trap Detection / 第四层：多技术栈陷阱检测 (V2.7 NEW)

Not all projects are JavaScript. Different languages have their own "foot-guns" — patterns that look correct but silently cause bugs. 不是所有项目都用 JavaScript。不同语言有各自的"暗坑"——看起来正确但悄悄出错的模式。

Python Traps / Python 陷阱

# ❌ Trap P1: Mutable default arguments / 可变默认参数
def add_item(item, items=[]):  # BUG: items shared across all calls!
    items.append(item)
    return items

# ✅ Correct / 正确:
def add_item(item, items=None):
    if items is None:
        items = []
    items.append(item)
    return items

# ❌ Trap P2: Late Binding Closures / 延迟绑定闭包
funcs = [lambda x=i: x for i in range(3)]  # BUG: all return 2!
# ✅ Correct / 正确:
funcs = [lambda x=i: x for i in range(3)]  # actually still wrong...
# Really correct:
funcs = [(lambda v: lambda: v)(i) for i in range(3)]

# ❌ Trap P3: `is` vs `==` for value comparison / is用于值比较
if x is 1000:  # BUG: small ints cached but 1000 might not be
# ✅ Correct / 正确:
if x == 1000:

Rust Traps / Rust 陷阱

// ❌ Trap R1: Unbounded collect() on huge iterators / 无界collect()
let all: Vec<_> = huge_file.lines().collect();  // OOM risk!
// ✅ Correct: use iterators lazily / 惰性迭代
for line in huge_file.lines() { /* process one */ }

// ❌ Trap R2: Clone in hot loop instead of borrow / 热循环中clone而非借用
for item in items.clone() {  // unnecessary clone
// ✅ Correct:
for item in &items {  // borrow instead

Go Traps / Go 陷阱

// ❌ Trap G1: Loop variable capture in goroutines / goroutine闭包捕获循环变量
for _, item := range items {
    go func() {
        process(item)  // BUG: all use last item!
    }()
}
// ✅ Correct / 正确:
for _, item := range items {
    item := item  // capture per iteration
    go func() {
        process(item)
    }()
}

// ❌ Trap G2: Nil interface != nil concrete type / nil接口 ≠ nil具体类型
var p *MyStruct = nil
var i MyInterface = p
if i != nil {  // BUG: true! Interface is non-nil with nil concrete

Detection Rule / 检测规则

When opening a project file for modification:

1. Detect file extension → activate corresponding language trap checklist
2. .py → check P1/P2/P3 | .rs → check R1/R2 | .go → check G1/G2
3. .js/.ts → standard Traps A/B/C (Layer 3) still apply
4. Unknown language → skip multi-stack check, but still apply universal Principles

Progressive Activation by Change Size / 按改动大小分层激活 (V2.7 NEW)

Not every change needs the full three-layer discipline. Match depth to change impact. 不是每次改动都需要三层全开。按改动影响面匹配合适的深度。

Change size assessment / 改动规模评估:
  ├── ≤ 3 files + ≤ 30 net lines → L1 Lightweight / 轻量
  │   Execute: Pre-Gate 1 (Three Questions) + Principles 1-5 (skip full Gate 2/3)
  │   执行：前置门1（三问三答）+ 原则1-5（跳过高开销的门2/3）
  │
  ├── 3-10 files OR involves routes/data-flow → L2 Standard / 标准
  │   Execute: All 3 Pre-Gates + All 6 Principles + All 3 Traps
  │   执行：全部前置门 + 全部六大原则 + 全部三大陷阱
  │
  └── > 10 files OR new feature/refactor → L3 Full / 完整
      Execute: Full L2 + Intent Anchor Pre-Judgment explicit output required
      执行：完整L2 + 意图锚点预判必须显式输出

L1 skip rules / L1 可跳过: Gate 2 (Repeat Bug — not relevant for tiny fixes), Breadcrumb scan (small change rarely affects coupling) L2 minimum: All gates + principles + traps must run. User can upgrade to L3 manually: "用完整L3" L3 required: New feature dev, architecture refactor, cross-module changes

Summary Checklist / 总结检查清单（Run Through Before Outputting Code / 输出代码前逐项检查）

□ Gate 1 — Three Questions / 三问三答: Full call chain? All branches? Unified fix or patch?
□ Gate 2 — Repeat Bug / 重复Bug: Fixed 2+ times already? → Search first, don't code
□ Gate 3 — File Size / 文件大小: Target file >300 lines? New feature needs new file?
□ Principle 0 — 🍞 Breadcrumb Pre-Scan / 面包屑预扫描: Open file → scan header → parse @COUPLED/📖
□ Principle 1 — Think First + Intent Anchor Pre-Judgment / 先思考+意图锚点预判: What tags will I need?
□ Principle 2 — Subtraction First / 做减法: Can I delete code instead of adding?
□ Principle 3 — Keep It Simple / 保持简单: Minimal changes, no over-engineering
□ Principle 4 — Precise Modification / 精准修改: Only target code, confirm all branch paths
□ Principle 5 — Goal-Driven / 目标驱动: Will it run? Verify immediately → close loop
□ Trap A — Falsy Coercion / 假值强制: Using `||` on numeric values?
□ Trap B — Select Fake-Selection / Select假选中: `<select>` has placeholder option?
□ Trap C — POST-as-UPSERT: UPDATE branch reads from `req.body`?

Appendix: Classic Patch Anti-Patterns Quick Reference / 附录：经典补丁反模式速查

The following are typical patch anti-patterns extracted from real projects. Alert immediately when encountering similar patterns. 以下是从真实项目中提取的典型补丁反例，遇到类似模式立刻警觉。

Related Skill Orchestration / 关联Skill编排

This Skill is the first link in the Vibe Coding Rules pipeline / 本Skill是流水线的第一环节:

coding-principles ← This Skill (pre-code mandatory) / 本Skill（改前强制）
    ├── Layer 1: Pre-Gates (Three Questions + Repeat Bug + File Size)
    ├── Layer 2: Six Principles (🍞 Pre-Scan → Think First → Subtraction → Simple → Precise → Goal-Driven)
    ├── Layer 3: Three Traps (|| falsy / select fake / POST hardcode)
    ↓
safe-terminal-executor (if API verification needed) / 如需API验证
    ↓
Write/Modify Code / 写/改代码
    ↓
self-check (28 rules + trust tiers + four-hop chain + 🛑 integrity gate V2.6 + 🍞 auto-seeding) / 自检
    ↓
web-testing (browser automation: DOM + screenshot + OCR, mandatory when gate passes) / 自动化测试
    ↓
changelog (change log + growth detection + anti-bloat) / 变更日志
    ↓
git commit / 自动存档
    ↓
✅ Delivery Closed Loop / 交付闭环

Sources / 参考来源

Inspired by observations from the AI coding community on how AI-assisted programming changes development workflows.

• Community reference: https://x.com/karpathy/status/2015883857489522876
• Related project: https://github.com/forrestchang/andrej-karpathy-skills

Safe Terminal Executor / 安全终端执行器

Core Rule: No Bare Commands — Everything Through Scripts / 核心规则：禁止裸命令——所有操作通过脚本执行

安全包装所有网络请求（curl/wget），强制带超时保护 + 进程退出保证 + 日志输出，防止命令卡死。

Safe wrapper for all network requests (curl/wget). Enforces timeout protection + guaranteed process exit + log output to prevent hung commands.

Lightweight Fast Track / 轻量快速通道（V2.6）

Commands meeting ALL of the following can run directly — no .cjs script needed / 满足以下全部条件的命令可直接运行，无需生成脚本：

• Single-line curl/wget with built-in timeout (--connect-timeout N --max-time N) / 单行命令且自带超时参数
• No pipe (|) or redirect (>) / 无管道或重定向
• Response expected < 10 lines / 预期响应少于10行
• NOT writing to a file (no -o or >) / 不写入文件

# ✅ Allowed（自带超时 + 无管道 + 只读）
curl --connect-timeout 5 --max-time 10 https://example.com/api/health

# ❌ Still forbidden（无超时 / 有管道 / 写文件）
curl https://example.com          # missing timeout
curl ... | bash                   # dangerous pipe
curl -o output.txt ...            # writes to file

Why: For quick health checks, generating a full .cjs script adds unnecessary friction. But timeout is non-negotiable. / 快速健康检查不必每次都生成完整脚本，但超时保护不可妥协。

5-Step Workflow

1 — Classify Command Type

Check if it contains network requests. Yes → continue. No → judge per table above.

2 — Generate Test Script

Convert command to .cjs script, store in project {{pipeline.paths.tests}} directory:

• Naming: {{pipeline.paths.tests}}test-{feature}-{date}.cjs
• Must include: timeout guard, step logs, explicit process.exit

const TIMEOUT = setTimeout(() => {
  console.error('FAIL: Request timed out');
  process.exit(1);
}, 10000);
console.log('[1/3] Sending request...');

3 — Display Script and Confirm

Show full script, brief explanation, wait for confirmation before execution.

4 — Execute + Report

Run node {{pipeline.paths.tests}}test-xxx.cjs, report results.

5 — Clean Up

Delete one-off scripts after execution. Keep reusable scripts.

POST Request Template

const http = require('http');
const TIMEOUT = setTimeout(() => { console.error('FAIL: Request timed out'); process.exit(1); }, 10000);

const body = JSON.stringify({ /* request params */ });
const options = {
  hostname: '{{pipeline.project.host}}',
  port: {{pipeline.project.port}},
  path: '/your-endpoint',
  method: 'POST',
  headers: { 'Content-Type': 'application/json', 'Content-Length': Buffer.byteLength(body) }
};

console.log(`[1/3] POST ${options.hostname}:${options.port}${options.path}`);
const req = http.request(options, res => {
  clearTimeout(TIMEOUT);
  let data = '';
  res.on('data', c => data += c);
  res.on('end', () => {
    console.log(`[3/3] HTTP ${res.statusCode}: ${data.substring(0, 300)}`);
    process.exit(res.statusCode >= 400 ? 1 : 0);
  });
});
req.on('error', e => { clearTimeout(TIMEOUT); console.error(`FAIL: ${e.message}`); process.exit(1); });
req.write(body);
req.end();

GET Request Template

const http = require('http');
const TIMEOUT = setTimeout(() => { console.error('FAIL: Request timed out'); process.exit(1); }, 10000);

const options = {
  hostname: '{{pipeline.project.host}}',
  port: {{pipeline.project.port}},
  path: '/your-endpoint',
  method: 'GET'
};

console.log(`[1/2] GET ${options.hostname}:${options.port}${options.path}`);
const req = http.request(options, res => {
  clearTimeout(TIMEOUT);
  let data = '';
  res.on('data', c => data += c);
  res.on('end', () => {
    console.log(`[2/2] HTTP ${res.statusCode}: ${data.substring(0, 300)}`);
    process.exit(res.statusCode >= 400 ? 1 : 0);
  });
});
req.on('error', e => { clearTimeout(TIMEOUT); console.error(`FAIL: ${e.message}`); process.exit(1); });
req.end();

Division of Labor with web-testing

The two Skills are complementary, not overlapping.

Post-Code-Change Self-Check V2.7 / 代码修改后自检 V2.7

Overview / 概述

每次代码修改后的强制自检流程。逐项遍历 29 条规则，防止重复已知 Bug 模式。V2.5 新增面包屑自动播种，V2.6 新增完整性阻断点（防纸面自检伪完成），V2.7 新增失败恢复模式 + 优雅降级，V2.9 新增规则29 文件行数检查。

Mandatory self-check process after every code change. Iterates through 29 rules item by item to prevent repeating known bug patterns. V2.5 adds breadcrumb auto-seeding, V2.6 adds integrity gate (prevents paper-only false completion), V2.7 adds failure recovery + graceful degradation, V2.9 adds rule 29 file-size auto-check.

Trigger Conditions (read from pipeline.json)

Must execute when any of the following occurs:

• {{#if hasToolDirectory}}Modifying files in {{pipeline.architecture.toolDirectory}}{{/if}}
• Modifying tool schema (name/description/parameters)
• {{#if hasThreeLayerRegistration}}Modifying {{pipeline.architecture.fallbackToolsConstant}} fallback list{{/if}}
• Modifying core task-link code
• {{#if hasDualEntry}}Modifying dual-entry HTML files{{/if}}
• Modifying Express routes
• Modifying database schema

Self-Check Workflow / 自检流程

Step -1: Pre-Modification Anchor Scan (V2.4+)

Before writing any code, scan target files for existing anchors (executed in coding-principles Principle 0):

1. Scan @COUPLED tags: record all coupled file paths → add them to self-check scope
2. Scan 📖 references: record all referenced docs → read their "Implementation Location" sections
3. Scan 🍞 breadcrumb header: if file has 🍞 block → parse @COUPLED/📖/@GOTCHA/@BUGFIX for navigation context
4. If no 🍞 header: mark "this file needs breadcrumb seeding after changes"

Step 0: Locate Rules by Code Type Changed

Based on what you changed, use the index to locate relevant rules. See references/self-check-full.md Section 0. You don't need to iterate all 28 rules — only check rules triggered by your change type.

Quick index reference:

Step 0.6: Breadcrumb Auto-Seeding 🍞 (V2.5 NEW — Mandatory for Every File Changed)

Breadcrumbs are the AI's project map. This step ensures every code change automatically plants breadcrumbs, so any future AI opening the same file can navigate without extra context.

For every modified file:

A. File has NO 🍞 header → Create one: Insert the standard 🍞 navigation block at the file header (after 'use strict', before first import/require):

/*
 * ─── 🍞 AI Breadcrumb Navigation ──────────────────
 * Tag meanings: @COUPLED=linked files @GOTCHA=gotcha @BUGFIX=bug fix @MAGIC=magic number
 *              @DEPENDS=external dependency @ASSUME=assumption @TODO=todo @WHY=design rationale
 *              @PERF=performance @CONTRACT=interface contract 📖=dev doc reference
 * 
 * Breadcrumbs (changing this affects):
 *   @COUPLED sync needed: fileA, fileB
 *   📖 see: docs/xxx/yyy.md
 * ──────────────────────────────────────────────────
 */

Auto-fill breadcrumbs detected during this change:

• a) @COUPLED: which other files were modified in this session? → mutual cross-reference
• b) 📖: which dev docs were read during this change? → link them
• c) @BUGFIX: is this a bug fix? → add date + reason + solution
• d) @GOTCHA: any counter-intuitive patterns? → mark the trap
• e) @MAGIC: any hardcoded business numbers? → annotate meaning

B. File already HAS 🍞 header → Update it:

1. Verify existing @COUPLED file paths still exist
2. Verify existing 📖 doc paths still exist
3. Add new breadcrumbs from this change
4. Remove/stale-mark expired breadcrumbs

C. Breadcrumb quality requirements (block if violated):

• @COUPLED must specify file paths (or file+line), NOT vague "all frontend files"
• 📖 must point to real existing documents → block if missing
• @BUGFIX must include date + brief reason + fix approach

D. Insertion position rules by language:

• JavaScript/TypeScript: after 'use strict';, before first import/require
• HTML: after <!DOCTYPE html>, before <head> (use <!-- --> comments)
• CSS: first line (use /* */ comments)
• Python: after #! shebang, before first import (use # lines, replace 🍞 with [breadcrumb])
• Markdown: after # title, before body text (use <!-- --> HTML comments)

Why this format is AI-readable without any external docs:

• 🍞 emoji = visual anchor, AI can grep /🍞/ to locate instantly
• Tag meanings line = inline cheat sheet, no need to read ANCHOR_SPEC.md
• @COUPLED + file list = tells AI exactly which files to change together
• 📖 + doc path = entry point to detailed design docs
• @BUGFIX + date = prevents regressions

This step ensures: every code change = one breadcrumb planted automatically. No manual effort needed.

Step 1: Architecture Registration Check (optional, per pipeline.json config)

{{#if hasThreeLayerRegistration}} Check consistency between {{pipeline.architecture.toolDirectory}} and {{pipeline.architecture.fallbackToolsConstant}}. Confirm count is {{pipeline.architecture.toolCount}}. {{else}} Skip (project pipeline.json has architecture.hasThreeLayerRegistration = false) {{/if}}

Step 2: Schema Field Completeness (if tools involved)

Confirm each tool entry has complete name/description/parameters.

Step 3: Implementation Location Cross-Validation (V2.4+ — Four-Hop Chain)

If this change involves dev docs or code referenced in docs' "Implementation Location":

1. Changed docs → verify "Implementation Location" sections are still accurate
2. Changed code → search which docs' "Implementation Location" references this file → check if they need updates
3. 📖 bi-directional verification:
   • Code 📖 path → doc exists?
   • Doc "Implementation Location" → code path exists?
   • Either broken → fix or mark (block if path missing, warn if content mismatch)

Step 4: Truncation Point Scan (if data transport involved)

{{#if hasTruncationPoints}} Check all configured truncation points: {{#each pipeline.architecture.truncationPoints}}

• {{this}} {{/each}} Confirm truncation limits can accommodate maximum data volume. {{else}} Skip (no truncation points configured) {{/if}}

Step 5: Iterate Through 29 Rules

Select relevant rules by change type. Core rule quick reference:

Step 6: Historical Incident Pattern Match

Think: Could this change reproduce a known incident pattern? Reference references/incident-history.md.

Step 6.5: Trust-Tiered Rule Check (V2.1+)

This step handles self-growing system generated Trust-Tiered rules. Only executes when project .ai-pipeline/ exists.

1. Read observation pool: read_file("references/observations.md")

   • Check if any Tier 0 observation entries relate to this change
   • If related, record "this pattern has been observed N times before"

2. Read auto-grown rules: Check [SOFT] and [HARD] marked rules at the end of self-check-full.md in the [Auto-Grown Rules Zone]

   • [HARD] rules → mandatory block, must fix
   • [SOFT] rules → warn, suggest fix but skippable

3. User resistance demotion: If user explicitly says "ignore this rule" or "skip this":

   • Record demotion event in growth-log.md
   • [HARD] → demote to [SOFT] (confidence -2)
   • [SOFT] → demote back to observations.md observation pool (confidence -2)
   • Confidence hits 0 → move to retired.md

4. Retired rule check: read_file("references/retired.md")

   • If current change pattern matches a retired rule, do NOT alert again

5. Rule bloat sanity check (V2.2): Quick count of active rules

   • Count [SOFT] + [HARD] rules in self-check-full.md
   • If total > antiBloat.maxTotalRules (default 30): warn user
   • If [HARD] > antiBloat.maxHardRules (default 15): same warning

Step 6.6: Self-Check Integrity Gate / 自检完整性阻断点 (V2.6 NEW)

Steps 0-6.5 are all analytical operations (reading files, doing diffs, checking rules). These operations themselves create an illusion of "I've checked everything." Step 7 (Automated Testing) is an execution-type operation, fundamentally different in mode. Place a hard gate at the fracture point between analysis and execution.

步骤 0-6.5 全是分析型操作（读文件、做 diff、检查规则），这些操作本身会给人"已经查完了"的错觉。步骤 7 是执行型操作，模式完全不同。在分析模式和执行模式之间的断裂点设置硬性门禁。

After Step 6.5 completes, before Step 7, verify item-by-item / 逐项确认：

• □ Have Steps 0-6.5 all been completed? (No step may be skipped)
• □ Has Step 7 (Automated Testing) been queued for execution?
• □ If Step 7 has NOT been executed → BLOCK here, prohibit proceeding to Step 8 (Changelog) or git commit

Block consequence / 阻断后果: Skipping Step 7 to write changelog directly = paper-only false completion. Paper checks passed + not actually run tests = illusion of "everything is fine." Self-check = paper checks + actual verification, one step short = not done.

Why this gate is necessary / 为什么需要这个门禁: Without it, the AI's natural tendency to stop after analytical steps (all reads/diffs/logic checks feel like "completion") will cause the pipeline to silently truncate at Step 6.5. This gate forces the mode switch from analysis to execution.

Step 6.7: Failure Recovery Mode / 失败恢复模式 (V2.7 NEW)

When self-check finds too many violations, don't block delivery — group and prioritize. This prevents the pipeline from becoming a bottleneck on legacy codebases. 自检发现过多违规时，不要阻塞交付——分组优先级处理。防止流水线在遗留代码上变成瓶颈。

Activation threshold / 激活阈值: ≥ 5 violations found in a single self-check run.

When triggered:

┌── Failure Recovery Grouping / 失败分组 ──────────────────────
│
│ 🔴 HARD (must fix before merge / 合并前必须修):
│   [list violations that would cause runtime errors or data loss]
│   [列出会导致运行时错误或数据丢失的违规]
│
│ 🟡 SOFT (fix in next session / 下次修改时修):
│   [list violations that are quality issues but won't break]
│   [列出质量缺陷但不影响运行的问题]
│
│ ⚪ BASELINE (record as tech debt / 记录为技术债务):
│   [list violations that predate this change]
│   [列出本次改动之前就存在的违规]
│
│ Decision / 决策:
│ □ HARD = 0 → ✅ Proceed to Step 7 (testing) / 继续到步骤7
│ □ HARD > 0 → 🛑 Fix HARD items → re-check → then proceed
│ □ SOFT + BASELINE → Log to changelog, do NOT block delivery
│
└──────────────────────────────────────────────────────────────

Key principle / 关键原则:

• Only HARD violations block the pipeline. SOFT + BASELINE are recorded but don't halt.
• BASELINE items are auto-marked for re-check on next edit of the same file.
• If the same BASELINE item appears 3+ times across sessions → upgrade to SOFT.

Step 6.8: Graceful Degradation / 优雅降级 (V2.7 NEW)

The pipeline should never crash because optional infrastructure is missing. Degrade gracefully instead of blocking entirely. 流水线不应因为可选的基建缺失而崩溃。优雅降级而非完全阻断。

Degradation golden rule / 降级黄金守则: Always print which steps were skipped and why. Never silently skip.

Step 7: Automated Testing / 自动化测试 (mandatory when gate passes)

{{#if pipeline.skills.webTesting.enabled}} After self-check integrity gate passes, execute automated tests:

• Check if project {{pipeline.paths.tests}} has test scripts
• Run tests and confirm all pass {{else}} WARNING: webTesting not enabled in pipeline.json — this does NOT exempt from Step 6.6 gate. If no automated test suite exists, perform manual verification before proceeding to Step 8. {{/if}}

Step 8: Changelog (mandatory)

After self-check + tests all pass, record this change:

• Format: change summary → file list → new deps → self-check digest
• Write to {{pipeline.paths.changelogFormat}}
• Must NOT skip or "do it later"

Related Skill Orchestration

coding-principles (pre-code check + breadcrumb pre-scan 🍞 V2.5)
    ↓
safe-terminal-executor (if API verification needed)
    ↓
self-check (post-code check) ← This Skill
    ├── Step -1: pre-modification anchor scan
    ├── Step 0: locate rules by code type
    ├── Step 0.6: 🍞 breadcrumb auto-seeding (V2.5)
    ├── Step 1-2: architecture diff + schema
    ├── Step 3: implementation cross-validation (four-hop chain)
    ├── Step 4: truncation point scan
    ├── Step 5: iterate 29 rules
    ├── Step 6: incident pattern match
    ├── Step 6.5: trust-tier check
    ├── Step 6.6: 🛑 integrity gate (V2.6 — blocks if testing not queued)
    ├── Step 6.7: 🔄 failure recovery mode (V2.7 — HARD/SOFT/BASELINE grouping)
    ├── Step 6.8: ⚠️ graceful degradation (V2.7 — skip missing infra, never crash)
    ↓
web-testing (automated testing, mandatory when gate passes)
    ↓
changelog (change log)
    ↓
git commit
    ↓
Delivery closed loop

Resources

• references/self-check-full.md — Complete self-check document (28 rules + auto-grown zone + V2.5 four-hop chain + 🍞 breadcrumbs)
• references/incident-history.md — Historical incident root cause + lesson quick reference
• references/observations.md — Tier 0 observation pool (V2.1+)
• references/retired.md — Retired rules archive (V2.1+)
• references/growth-log.md — Growth event log (V2.1+)

Vibe Coding Rules V2.7

AI 写代码最大的敌人，是它自己——它会忘记昨天修好的 Bug，会在同一个坑里反复跌倒。

6 个会自我进化的 Skill，给 AI 装上"编程纪律"。从改前自查到变更记录，一条流水线闭环交付。 V2.7 新增渐进式采纳：改3行不用跑全套，改功能才走全链路。按需激活，不浪费上下文。

AI's biggest enemy is itself — it forgets the bugs it fixed yesterday. 6 self-evolving Skills. V2.7 adds Progressive Adoption: 3-line fix ≠ full pipeline. Activate only what's needed.

⚡ Before & After / 装前装后

🎯 Progressive Adoption / 渐进式采纳 (V2.7 NEW)

不是每次改动都需要跑 6 个 Skill。按改动大小自动匹配合适的纪律层数，避免浪费上下文。 Not every change needs all 6 Skills. Match discipline depth to change size. Save context.

自动降级规则 / Auto-downgrade rules：

• 改动项目中检测到 5+ 个违规 → 不阻塞交付，但标记为 BASELINE（基线债务），下次同模块改动时升级为 L3
• 改动 safe-terminal-executor 始终可用，无论 L1/L2/L3（网络命令安全封装不需要上下文代价）
• 用户可手动指定层级：「用 L2 自检」或「走完整 L3」

📦 Install / 安装

# CodeBuddy / Cursor / Windsurf
openclaw skills install @ron-dali/vibe-coding-rules

# 或手动
git clone https://github.com/Ron-dali/vibe-coding-rules.git

安装后对 AI 说："初始化流水线"，AI 自动检测项目并配置。

Pipeline Architecture / 流水线架构

          │   └→ coding-principles（五大原则 + 面包屑预扫描）
          │
          ├── L2 标准（3-10文件，或涉及路由/数据流）
          │   └→ L1 + self-check（28条规则 + 阻断点 + 面包屑播种）
          │
          └── L3 完整（>10文件，或新功能/重构）
              └→ L2 + web-testing + changelog → ✅ 闭环交付

coding-principles (5 Principles + 🍞 Breadcrumb Pre-scan / 改前五大原则 + 面包屑预扫描)
  → safe-terminal-executor (Safe Terminal Exec / 安全终端执行，始终可用)
    → Write/Modify Code / 编写修改代码
      → self-check (28 Rules + Integrity Gate 🛑 + Breadcrumb Seeding / 28条规则自检 + 完整性阻断点 + 面包屑播种)
        → web-testing (Auto Regression Test / 自动化回归测试，阻断点通过后强制)
          → changelog (Changelog + Growth Detection / 变更日志 + 生长检测)
            → ✅ Closed Loop / 闭环交付

Included 6 Skills / 包含的 6 个 Skill

Core Features / 核心特性

• 🎚️ Progressive Adoption L1/L2/L3 / 渐进式采纳 — 改3行用L1轻量自检，改功能走L3全链路，按需激活不浪费上下文 / Match discipline depth to change size. No overkill.
• 🔄 Self-Growing Rules / 规则自生长 — Today's pitfall becomes tomorrow's hard rule the AI can't break / 今天踩的坑，明天变成AI不能再犯的硬规则
• 🍞 Breadcrumb System V2.7 / 面包屑系统 — Auto-plant coupled files + historical gotchas in file headers, AI never forgets / 文件头部自动播种耦合关系+历史坑位，AI不再失忆
• 🎯 Trust-Tiered Growth / 信任分级 — Tier0 Observation Pool → Tier1 [SOFT] → Tier2 [HARD], auto promote/demote / 观察池→软规则→硬规则，自动晋升退役
• 🛡️ Failure Recovery Mode / 失败恢复模式 — 5+ violations → HARD/SOFT/BASELINE 分组，不阻塞交付 / Multi-violation grouped recovery, delivery unblocked
• 🌍 Cross-Platform / 跨界兼容 — Works with CodeBuddy, Cursor, Windsurf / 三种AI Agent通用

Who Needs This? / 谁需要这个？

• 🐣 AI coder who doesn't know programming → Discipline exoskeleton / 用AI写代码但不懂编程 → 编程纪律外骨骼
• 💻 Solo dev / one-person company → Your own QA team / 独立开发者一人公司 → 自己的QA团队
• 🏢 Small team using AI assistance → Unified quality standards / 小型团队用AI辅助 → 统一质量标准
• 🤖 Heavy AI Agent user → Agent gets smarter over time / 重度AI Agent用户 → Agent越用越聪明

Author / 作者

躺不平联盟 (TangBuPing) — A coding beginner who wrote 140,000 lines of code across a 3-platform system with AI, distilling every painful lesson into these 6 Skills. 代码小白用AI写140000行三端平台，把踩坑经验沉淀为这6个Skill。

GitHub · tangbuping.com

Web Automated Testing / Web自动化测试

Overview / 概述

自动化浏览器测试技能。使用 Playwright 进行浏览器交互与 DOM 断言，tesseract.js 做 OCR 截图文字验证。支持冒烟测试、全量测试、截图回归测试。

Automated browser testing Skill. Uses Playwright for browser interaction and DOM assertions, tesseract.js for OCR screenshot text verification. Supports smoke tests, full tests, and screenshot regression testing.

Trigger Conditions

• After code change self-check passes
• User asks to "test", "verify page"
• Need to confirm UI rendering correctness
• Screenshot regression testing

Configuration (read from pipeline.json)

Test Types / 测试类型

1. Smoke Test (fast, always run)

• Page loads successfully
• Key DOM elements exist
• No JS runtime errors

2. Full Test (after major changes)

• All interaction flows
• Form submissions
• Modal/overlay open/close
• Async data loading
• Screenshot comparison

3. OCR Verification (optional, requires tesseract.js)

• Screenshot text recognition
• Key copy verification
• Multi-language support

Workflow

Step 0: Project Type Detection / 项目类型检测（V2.6）

Before running any test, check whether this project actually needs browser testing / 先判断项目是否需要浏览器测试：

1. Check pipeline.json → project.type:
   • web / fullstack / spa / mini-program → Continue to Step 1
   • cli / backend-api / desktop / script → Skip this Skill: report "Web testing skipped — project type is {type}, no browser UI to test"
2. No pipeline.json → check package.json for web frameworks:
   • Contains react/vue/angular/next/nuxt/express with a start or dev script → likely web → continue
   • Otherwise → skip with note: "No web project detected — web-testing skipped"
3. Both files missing → check for .html files in project root:
   • Found → possible static web → continue with caution
   • Not found → skip

Why: Running Playwright on a CLI-only project wastes time and produces confusing errors. / 在纯CLI项目上跑Playwright浪费时间且报错混乱。

Step 1: Prepare

Check test dependencies installed:

npx playwright install chromium

Step 2: Create Test Script

Write test cases to {{pipeline.paths.tests}}smoke-test.cjs:

const { chromium } = require('playwright');
(async () => {
  const browser = await chromium.launch();
  const page = await browser.newPage();
  await page.goto('{{pipeline.project.testUrl}}{{pipeline.project.testPagePath}}');
  await page.waitForLoadState('networkidle');
  
  // DOM assertions
  const el = await page.$('{{pipeline.testing.domSelectors.mainContainer}}');
  if (!el) { console.error('FAIL: Main container not found'); process.exit(1); }
  
  console.log('OK: Page loaded successfully');
  await browser.close();
})().catch(e => { console.error('FAIL:', e.message); process.exit(1); });

Step 3: Execute

node {{pipeline.paths.tests}}smoke-test.cjs

Step 4: Report

Report test results: pass count / fail count, failed item screenshots and reasons.

Dependencies

npm install playwright
npx playwright install chromium
# OCR (optional)
npm install tesseract.js sharp