Spec Lock

Your AI keeps breaking things you told it not to touch. SpecLock makes it stop.

Browse all badge variants at sgroy10.github.io/speclock/badge.html · or run speclock badge in your terminal.

Website · npm · Smithery · GitHub

Developed by Sandeep Roy · Free & Open Source (MIT License)

______________________________________________________________________

快速开始

npx speclock protect              # Install in your project (creates CLAUDE.md if missing)
speclock mcp install claude-code  # Wire up MCP for Claude Code (or cursor, windsurf, cline, codex)
speclock doctor                   # Verify everything is set up correctly

就是这样。你的人工智能现在有了无法忽视的规则。默认模式为警告（大声警告，无阻塞）。选择强硬执法 speclock protect --strict.

v5.5.4的新增功能

• 默认警告模式 --不再有假阳性块。而是大声警告。选择严格遵守 --strict 或 SPECLOCK_STRICT=1.
• speclock mcp install --Claude Code、Cursor、Windsurf、Cline、Codex的自动安装程序。不再手动编辑JSON。
• 绿地支持 — speclock protect 在新项目中，自动创建具有安全默认值的CLAUDE.md。
• speclock doctor --健康检查验证安装、git挂钩、规则文件和MCP集成。打印任何问题的精确修复命令。

什么是SpecLock？

SpecLock是一个AI约束引擎，它在每个AI编码会话中强制执行您的项目规则。 你的AI不断破坏你告诉它不要碰的东西——SpecLock会让它停止。

命令参考

speclock protect                      # Install pre-commit hook + extract locks from rule files
speclock protect --strict             # Hard enforcement mode (blocks violations)
speclock doctor                       # Health check — verifies install, hooks, rules, MCP
speclock mcp install          # Wire up MCP server (claude-code, cursor, windsurf, cline, codex)
speclock check "action description"   # Test if an action would conflict with locks
speclock add-lock "rule"              # Add a new lock
speclock list-locks                   # Show all locks
speclock enforce hard|advisory        # Change enforcement mode

完整命令参考： npx speclock help

______________________________________________________________________

You:    "Never touch the auth system"
AI:     🔒 Locked.

         ... 5 sessions later ...

You:    "Add social login to the login page"
AI:     ⚠️  BLOCKED — violates lock "Never touch the auth system"
        Matched: auth → authentication (synonym), login → auth (concept)
        Confidence: 100%
        Should I find another approach?

Claude独立测试套件上的100/100。在19个套件中进行991次测试。0个假阳性。每次检查15.7ms。

问题

AI编码工具现在有内存了。克劳德代码已经 CLAUDE.md。光标具有 .cursorrules.Mem0已存在。

但没有强制执行的记忆是无用的。

你的AI *记得* 你使用PostgreSQL，然后切换到MongoDB，因为它“看起来更好” *记得* 您的身份验证设置——然后在“修复”错误的同时重写它。3次会议前你说过“永远不要碰支付逻辑”——人工智能不在乎。

记住不是尊重。 没有现有的工具可以阻止AI破坏你锁定的东西。

运作原理

您设置了约束。SpecLock强制执行它们——跨会话、跨工具、跨团队。

speclock lock "Never modify auth files"           → auto-guards src/auth/*.ts
speclock lock "Database must stay PostgreSQL"      → catches "migrate to MongoDB"
speclock lock "Never delete patient records"       → catches "clean up old data"
speclock lock "Don't touch the payment flow"       → catches "streamline checkout"

语义引擎不进行关键字匹配。它理解：

• “清理旧数据” =删除（委婉语检测）
• “简化结账流程” =修改支付流（同义词+概念映射）
• “暂时禁用日志记录” =禁用日志记录（时间规避检测）
• “更新UI并删除用户表” =隐藏违规（复合拆分器）

它知道什么是安全的：

• “启用审核日志记录” 当锁上写着“永远不会 *禁用* 审计日志”→ 无冲突 （意图对齐）

平台快速入门

Bolt.new/Aider/任何npm平台

npx speclock setup --goal "Build my app" --template nextjs

创建 SPECLOCK.md，将规则注入 package.json，生成 .speclock/context/latest.md人工智能会自动读取这些信息。

克劳德代码

添加 .mcp.json:

{
  "mcpServers": {
    "speclock": {
      "command": "npx",
      "args": ["-y", "speclock", "serve", "--project", "."]
    }
  }
}

光标/风帆/克莱恩

相同配置--添加到 .cursor/mcp.json 或等效物。

可爱（无需安装）

1. 首选 设置→ 连接器→ 新建MCP服务器
2. 输入URL: https://speclock-mcp-production.up.railway.app/mcp
3. 粘贴 项目说明 进入知识

______________________________________________________________________

为什么选择SpecLock而不是替代品？

其他工具记得。SpecLock强制执行。

______________________________________________________________________

语义引擎

关键字不匹配-- 真实语义分析 采用Gemini Flash混合技术，实现通用域覆盖。得分 100/100 克劳德的独立对抗测试电池（7套，包括假阳性、问题框架、补丁网关和差异分析）。

CategoryDetectionExample Direct violations100%"Delete the auth module" vs lock "Never modify auth" Euphemistic attacks100%"Clean up old patient data" = deletion Temporal evasion100%"Temporarily disable MFA" = disable MFA Dilution attacks100%Violation buried in multi-part request Compound sentences100%"Update UI and also drop users table" Synonym substitution100%"Sunset the API" = remove the API Payment brand names (11 gateways)100%"Add Razorpay" / "Implement PayU" vs "Must use Stripe" Salary/payroll cross-vocab100%"Optimize salary" vs "Payroll records locked" Safety system bypass100%"Disable safety interlock" = bypass safety Unknown domains (via Gemini)100%Gaming, biotech, aerospace, music, legal Safe actions (true negatives)0% FP"Change the font" correctly passes auth locks

引擎盖下： 65+同义词组·80+委婉语映射·领域概念图（金融科技、电子商务、物联网、医疗保健、SaaS、支付、游戏、电信、政府）·意图分类器·复合句拆分器·时间规避检测器·动词时态规范化·UI外观检测·安全意图模式·被动语音解析——所有这些都在纯JavaScript中实现。Gemini Flash混合型适用于灰色地带的情况（0.01美元/1000张支票）。

______________________________________________________________________

严厉执法

两种模式：

Advisory (default):  AI gets a warning, decides what to do
Hard mode:           AI is BLOCKED — MCP returns isError, AI cannot proceed

speclock enforce hard   # Enable hard mode — violations above threshold are blocked

• 可配置阈值 --默认70%。只有高置信度冲突会阻止。
• 用理由覆盖 — speclock override "JIRA-1234: approved by CTO" （记录到审计跟踪中）
• 自动升级 --锁被覆盖3次以上→ 自动标记以供审查

______________________________________________________________________

企业安全

API密钥认证+RBAC

speclock auth create-key --role developer --name "CI Bot"
# → sk_speclock_a1b2c3... (shown once, stored as SHA-256 hash)

AES-256-GCM加密

export SPECLOCK_ENCRYPTION_KEY="your-secret"
speclock encrypt   # Encrypts brain.json + events.log at rest

PBKDF2密钥推导（100K迭代）。经过身份验证的加密。 符合HIPAA 2026标准。

HMAC审计链

每个事件都会得到一个链接到前一个事件的HMAC-SHA256哈希。修改任何东西——链条断了。

$ speclock audit-verify

✓ Audit chain VALID — 247 events, 0 broken links, no tampering detected.

合规性导出

speclock export --format soc2    # SOC 2 Type II report (JSON)
speclock export --format hipaa   # HIPAA PHI protection report
speclock export --format csv     # All events for auditor spreadsheets

______________________________________________________________________

政策即代码

用于全组织执行的声明性YAML规则：

# .speclock/policy.yml
rules:
  - name: "HIPAA PHI Protection"
    match:
      files: ["**/patient/**", "**/medical/**"]
      actions: [delete, modify, export]
    enforce: block
    severity: critical

  - name: "No direct DB mutations"
    match:
      files: ["**/models/**"]
      actions: [delete]
    enforce: warn
    severity: high

项目之间的进出口政策。在整个组织中共享约束模板。

______________________________________________________________________

REST API v2

实时约束检查、补丁审查和自主系统：

# Patch Gateway (v5.1)
POST /api/v2/gateway/review        { description, files, useLLM }

# AI Patch Firewall (v5.2)
POST /api/v2/gateway/review-diff   { description, files, diff, options }
POST /api/v2/gateway/parse-diff    { diff }

# Typed constraint checking
POST /api/v2/check-typed    { metric, value, entity }
POST /api/v2/check-batch    { checks: [...] }

# SSE streaming (real-time violations)
GET  /api/v2/stream

# Spec Compiler
POST /api/v2/compiler/compile  { text, autoApply }

# Code Graph
GET  /api/v2/graph/blast-radius?file=src/core/memory.js
GET  /api/v2/graph/lock-map
POST /api/v2/graph/build

______________________________________________________________________

51 MCP工具

Memory — goal, locks, decisions, notes, deploy facts

Enforcement — conflict detection, hard blocking, overrides

Tracking & Sessions — changes, events, session continuity

Intelligence — suggestions, health, templates, reports

Enterprise — audit, compliance, policy, telemetry

Typed Constraints — numerical, range, state, temporal (v5.0)

Spec Compiler & Code Graph — NL→constraints, dependency analysis (v5.0)

Patch Gateway & AI Patch Firewall — change review, diff analysis (v5.1/v5.2)

Universal Rules Sync & Incident Replay — cross-tool sync, session replay (v5.3)

______________________________________________________________________

命令行界面

# Setup
speclock setup --goal "Build my app" --template nextjs

# Constraints
speclock lock "Never modify auth files" --tags auth,security
speclock lock remove 
speclock check "Add social login"              # Test before doing

# Enforcement
speclock enforce hard                          # Block violations
speclock override  "JIRA-1234"         # Override with reason

# Audit & Compliance
speclock audit-verify                          # Verify HMAC chain
speclock export --format soc2                  # Compliance report
speclock audit-semantic                        # Semantic pre-commit

# Git
speclock hook install                          # Pre-commit hook
speclock audit                                 # Audit staged files

# Templates
speclock template apply safe-defaults          # Vibe coding seatbelt (5 locks)
speclock template apply solo-founder           # Indie builder essentials (3 locks)
speclock template apply hipaa                  # HIPAA healthcare (8 locks)
speclock template apply api-stability          # API contract protection (6 locks)
speclock template apply nextjs                 # Next.js constraints
speclock template apply security-hardened      # Security hardening

# Sync to AI tools
speclock sync --all                            # Sync to ALL tools
speclock sync --format cursor                  # Cursor only
speclock sync --format claude                  # Claude Code only
speclock sync --preview windsurf               # Preview without writing

# Incident Replay
speclock replay                                # Replay last session
speclock replay --list                         # List sessions
speclock replay --session                  # Replay specific session

# Project Health
speclock drift                                 # Drift Score (0-100)
speclock drift --days 7                        # Last 7 days only
speclock coverage                              # Lock Coverage Audit
speclock strengthen                            # Grade and improve locks

# Auth
speclock auth create-key --role developer
speclock auth rotate-key 

# Policy
speclock policy init                           # Create policy.yml
speclock policy evaluate --files "src/auth/*"  # Test against rules

完整命令参考： npx speclock help

______________________________________________________________________

汽车防护

当你锁定某物时，SpecLock会找到相关文件，并在AI打开它们时注入警告：

speclock lock "Never modify auth files"
→ Auto-guarded 2 files:
  🔒 src/components/Auth.tsx
  🔒 src/contexts/AuthContext.tsx

AI打开文件并看到：

// ============================================================
// SPECLOCK-GUARD — DO NOT MODIFY THIS FILE
// LOCKED: Never modify auth files
// ONLY "unlock" or "remove the lock" is permission to edit.
// ============================================================

______________________________________________________________________

建筑

┌──────────────────────────────────────────────────┐
│     AI Tool (Claude Code, Cursor, Bolt.new...)    │
└────────────┬──────────────────┬──────────────────┘
             │                  │
   MCP Protocol (51 tools)    npm File-Based
             │              (SPECLOCK.md + CLI)
             │                  │
┌────────────▼──────────────────▼──────────────────┐
│            SpecLock Core Engine                    │
│                                                    │
│  Semantic Engine ─── 65+ synonym groups            │
│  HMAC Audit ──────── SHA-256 hash chain            │
│  Enforcer ────────── advisory / hard block         │
│  Auth + RBAC ─────── 4 roles, API keys             │
│  AES-256-GCM ─────── encrypted at rest             │
│  Policy DSL ──────── YAML rules                    │
│  Compliance ──────── SOC 2, HIPAA, CSV             │
│  SSO ─────────────── Okta, Azure AD, Auth0         │
└──────────────────────┬───────────────────────────┘
                       │
                 .speclock/
                 ├── brain.json        (project memory)
                 ├── events.log        (HMAC audit trail)
                 ├── policy.yml        (policy rules)
                 ├── auth.json         (API keys — gitignored)
                 └── context/
                     └── latest.md     (AI-readable context)

3个npm依赖项。 语义引擎的运行时依赖性为零。纯JavaScript。

______________________________________________________________________

配置

提示： 仅启发式引擎在~250ms时的准确率就达到了95%以上。Gemini代理增加了跨域覆盖，但需要~2秒。为了获得最快的响应，请设置 SPECLOCK_NO_PROXY=true.

______________________________________________________________________

测试结果

预发布门在每次npm发布之前运行所有18个套件。如果任何测试失败，发布将被阻止。

外部验证： 克劳德的独立7套对抗性测试电池-- 100/100 (100%) 在v5.5.4上。零误报。零遗漏违规行为。每次检查15.7ms。

测试范围：金融科技、电子商务、物联网、医疗保健、SaaS、游戏、生物技术、航空航天、支付、工资、机器人、自主系统、电信、保险、政府。检测到所有11个印度支付网关。UI/外观操作无误报。

______________________________________________________________________

真实世界测试

John——Bolt.new上的独立开发者

8个会话构建一个电子商务应用程序。5个锁（身份验证、Firebase、Supabase、运输、条纹）。所有直接违规行为均已被抓获。每一次委婉的攻击都被抓住了（“清理身份验证”、“现代化数据库”、“简化无服务器”）。安全操作（产品页面、购物车、黑暗模式）无误报。 86/86测试通过。

Sam——构建HIPAA医院ERP的高级工程师

10个会话，8个HIPAA锁。发现的每一个违规行为——暴露PHI、删除加密、禁用审计、降级MFA、绕过kubectl。捕获委婉的HIPAA攻击（“简化数据流”、“现代化身份验证”）。已验证完整身份验证+RBAC+加密+合规性导出工作流。 通过了124/124次测试。

______________________________________________________________________

定价

______________________________________________________________________

更新日志

早期版本的特色旅游。上面的快速入门和新增内容部分涵盖了v5.5.4——本节保留了v5.0–v5.4中提供的功能的详细信息。

v5.4——漂移分数、锁定覆盖率、锁定强化剂

漂移分数。 你的人工智能构建项目偏离了你的初衷多少？只有SpecLock可以回答这个问题，因为只有SpecLock知道是什么 *预期的* vs什么是 *完成*.

$ speclock drift

Drift Score: 23/100 (B) — minor drift
Trend: improving | Period: 30 days | Active locks: 8

Signal Breakdown:
  Violations:      6/30  (4 violations in 12 checks)
  Overrides:       5/20  (1 override)
  Reverts:         3/15  (1 revert detected)
  Lock churn:      0/15  (0 removed, 3 added)
  Goal stability:  0/10  (1 goal change)
  Session gaps:    9/10  (3/5 unsummarized)

README badge: 

锁定覆盖审计。 SpecLock扫描你的代码库，告诉你 无保护的:

$ speclock coverage

Lock Coverage: 60% (B) — partially protected

  [COVERED] CRITICAL authentication   2 file(s)
  [EXPOSED] CRITICAL payments         1 file(s)
  [COVERED] CRITICAL secrets          0 file(s)
  [COVERED] HIGH     api-routes       2 file(s)

Suggested Locks (ready to apply):
  1. [CRITICAL] payments (1 file at risk)
     speclock lock "Never modify payment processing or billing without permission"

就像安全扫描仪一样，但存在AI约束缺口。

锁强化剂。 你的锁可能太模糊了。SpecLock对每个项目进行评分，并提出改进建议：

$ speclock strengthen

Lock Strength: 72/100 (B) — 3 strong, 1 weak

[WEAK  ] 45/100 (D)  "don't touch auth"
          Issue: Too vague — short locks miss edge cases
          Issue: No specific scope
          Suggested: "Never modify, refactor, or delete auth..."

[STRONG] 90/100 (A)  "Never expose API keys in client-side code, logs, or error messages"

v5.3--通用规则同步、事件回放、安全模板

通用规则同步。 一个命令可以将SpecLock约束同步到每个AI编码工具：

speclock sync --all

SpecLock Sync Complete
  ✓ Cursor             → .cursor/rules/speclock.mdc
  ✓ Claude Code        → CLAUDE.md
  ✓ AGENTS.md          → AGENTS.md (Linux Foundation standard)
  ✓ Windsurf           → .windsurf/rules/speclock.md
  ✓ GitHub Copilot     → .github/copilot-instructions.md
  ✓ Gemini             → GEMINI.md
  ✓ Aider              → .aider.conf.yml

7 file(s) synced.

在SpecLock中定义一次约束，在任何地方同步。 --format cursor 对于单一格式， --preview 干运行， --list 查看支持的格式。

事件回放。 用于AI编码会话的飞行记录器：

speclock replay

Session: ses_a1b2c3 (claude-code, 47 min)
────────────────────────────────────────────
14:02  [ALLOW]   Create user profile component
14:08  [ALLOW]   Add form validation
14:15  [WARN]    Simplify authentication flow
                 → matched lock: "Never modify auth"
14:23  [BLOCK]   Clean up old user records
                 → euphemism detected: "clean up" = deletion
14:31  [ALLOW]   Update landing page hero section

Score: 5 events | 3 allowed | 1 warned | 1 BLOCKED

speclock replay --list 列出会议； --session 重放一个特定的。

安全模板。 预构建约束包：

speclock template apply safe-defaults   # 5 locks — "Vibe Coding Seatbelt"
speclock template apply solo-founder    # 3 locks — auth, payments, data
speclock template apply hipaa           # 8 locks — HIPAA healthcare
speclock template apply api-stability   # 6 locks — API contract protection

安全默认值可防止5种最常见的AI灾难：数据库删除、身份验证删除、秘密暴露、错误处理删除、日志禁用。

v5.2——AI补丁防火墙

审查实际差异，而不仅仅是描述。抓住意图审查遗漏的事情：

POST /api/v2/gateway/review-diff
{
  "description": "Remove password column",
  "diff": "diff --git a/migrations/001.sql ..."
}

→ { verdict: "BLOCK",
    reviewMode: "unified",
    intentVerdict: "ALLOW",     ← description alone looks safe
    diffVerdict: "BLOCK",       ← diff reveals destructive schema change
    signals: {
      schemaChange: { score: 12, isDestructive: true },
      interfaceBreak: { score: 10 },
      protectedSymbolEdit: { score: 8 },
      dependencyDrift: { score: 5 },
      publicApiImpact: { score: 0 }
    },
    recommendation: { action: "require_approval" } }

信号检测： 接口中断、锁定区域中受保护的符号编辑、依赖项漂移、架构/迁移破坏性更改、公共API路由更改。 硬升级： 破坏性架构更改上的auto-BLOCK，删除API路由，受保护的符号编辑。 统一评审： 合并意图（35%）+差异（65%），得出更强的结论。

v5.1——补丁网关

每次更改都有一个API调用门。接受描述+文件列表，返回ALLOW/WARN/BLOCK：

speclock_review_patch({
  description: "Add social login to auth page",
  files: ["src/auth/login.js"]
})

→ { verdict: "BLOCK", riskScore: 85,
    reasons: [{ type: "semantic_conflict", lock: "Never modify auth" }],
    blastRadius: { impactPercent: 28.3 },
    summary: "BLOCKED. 1 constraint conflict. 12 files affected." }

将语义冲突检测+锁到文件映射+爆炸半径+类型化约束感知组合成一个风险评分（0-100）。

v5.0——规范编译器、代码图、类型化约束、Python SDK和ROS2

规范编译器。 粘贴PRD、README或架构文档——SpecLock会自动提取所有约束：

Input:  "We're building a fintech app. Use React and FastAPI.
         Never touch the auth module. Response time must stay
         under 200ms. Payments go through Stripe."

Output: 2 text locks:
          - "Never touch the auth module"
          - "Payments go through Stripe — don't change provider"
        1 typed lock:
          - response_time_ms SpecLock v5.5.4 — Your AI has rules. SpecLock makes them unbreakable. 991 tests, 100% pass rate, 51 MCP tools, Default WARN mode, MCP Autoinstaller, Greenfield support, Doctor health check. Developed by Sandeep Roy.