May 2026 · Series "Trace Lock — Governance Notes from AI Pair-Programming" · Post 8 of 9
This is the engineering version of C1 Combined Offense + Defense, and also the convergence point of A2 Defense Engineering Edition and B2 Offense Engineering Edition.
A2 explains how to lock a single known trace using 5 artifacts. B2 explains how to fix N gaps surfaced by an audit using a 6-piece fix pattern. Each of those posts came with its own "cross-project reuse" table, but only covered its own side. This post merges the two tables into an 11-piece matrix, then adds cross-stack mapping, objective-vs-subjective project differences, AI pair-programming vs traditional development differences, plus an expanded "when not to use" list.
Written for engineers who already know A2's 5 artifacts and B2's 6-piece pattern. If you are a non-technical reader, C1 Combined Offense + Defense (plain version) is the post you want.
My environment: Vue 3 + Vite + Vitest + Supabase (PostgreSQL) + Node.js scripts. The "framework layer / content layer" split and porting cost estimates below are based on this stack. Moving to a different stack (Next.js + Prisma + Jest + tRPC, or Django + pytest + Celery) keeps the skeleton applicable, but code skeletons need to be replaced.
Merge A2's 5 artifacts with B2's 6-piece pattern. Deduplicate the overlap (Registry / Trace test / Governance rule are shared). Add each side's unique pieces. The result is an 11-piece total list:
| # | Piece | A2 uses? | B2 uses? | Main location | Reusability | Framework dependency |
|---|---|---|---|---|---|---|
| 1 | Registry markdown entry | ✅ | ✅ | |||
文檔/data-source-registry.md Critical Traces section |
||||||
| ★★★★★ | Pure markdown | |||||
| 2 | Trace test 5-section structure | ✅ | ✅ | frontend-app/src/__tests__/traces/T{NN}-*.trace.test.js |
||
| ★★★★☆ | Any unit test runner | |||||
| 3 | Governance rule A (trace-registry-test-coverage) | ✅ | ✅ | scripts/governance-guard.mjs |
||
| ★★★★☆ | Node.js script | |||||
| 4 | Governance rule B (trace-test-must-import-anchor) | ✅ | ✅ | scripts/governance-guard.mjs |
||
| ★★★★☆ | Node.js script | |||||
| 5 | AI reminder skill | ✅ | ⚠️ partial | |||
.claude/skills/trace-lock-modify/SKILL.md + .claude/skills/business-flow-audit-fix/SKILL.md |
||||||
| ★★★☆☆ | Claude Code / Cursor / other skill-enabled AI tools | |||||
| 6 | Pure-function helper convention | ❌ | ✅ | frontend-app/src/lib/business-rules/<feature>Logic.js |
||
| ★★★★★ | Pure JS module convention, framework-agnostic | |||||
| 7 | Caller exemption comment convention | ⚠️ occasional | ✅ | source code inline @xxx-ok: <reason> |
||
| ★★★★★ | Pure text regex convention | |||||
| 8 | Iteration log 5-section structure | ❌ | ✅ | 文檔/iteration-logs/<sprint>/NN_Gap-N_<topic>.md |
||
| ★★★★★ | Pure markdown record | |||||
| 9 | Reverse verification anchor-break flow | ⚠️ occasional | ✅ | 5-step flow (write test → green → break anchor → confirm red → revert) | ★★★★☆ | Pure procedure, needs team / AI cooperation |
| 10 | sql-only-trace variant | ⚠️ occasional | ✅ | |||
scripts/integration-test/T{NN}-*.sql + DO block |
||||||
| ★★★☆☆ | PostgreSQL-specific | |||||
| 11 | Decision Pinning (business contract freezing) | ❌ | ✅ | trace test's pin current behavior section + registry's backlog finding |
||
| ★★★★★ | Pure discipline, tool-agnostic |
A few observations.
Pull out pieces rated ≥ ★★★★☆:
Framework layer (high reusability):
1 Registry markdown entry ★★★★★
2 Trace test 5-section structure ★★★★☆
3 Governance rule A ★★★★☆
4 Governance rule B ★★★★☆
6 Pure-function helper convention ★★★★★
7 Caller exemption comment ★★★★★
8 Iteration log 5-section ★★★★★
9 Reverse verification anchor-break ★★★★☆
11 Decision Pinning discipline ★★★★★
Medium reusability (★★★☆☆):
5 AI reminder skill (tool-specific)
10 sql-only-trace variant (DB-specific)
Content layer (not reusable ★☆☆☆☆, reinvent per project):
- Specific traces (business chain shape)
- Specific helpers (business algorithm)
- Specific business contracts (pinning content)
- Specific incident pinning cases
A2 line 321 and B2 line 644 each observed "framework layer 80-90% reusable, business contract 0% reusable". The 11-piece matrix matches: 9 framework-layer pieces, 2 medium-tier pieces, business contract 0% reusable.
Both have strong framework dependencies.
Piece 5 AI reminder skill depends on Claude Code's skill auto-trigger mechanism (description-based fuzzy matching + frontmatter). Cursor has .cursorrules
with similar intent but different syntax. Other AI tools (GitHub Copilot / Continue.dev / Cody) currently lack this mechanism. Reusability depends on whether the target environment has the "skill auto-trigger" primitive:
Without this primitive, fall back to "PR template + checklist". But losing the "auto-trigger" property means relying on humans to remember the checklist, which becomes another rot source.
Piece 10 sql-only-trace variant depends on PostgreSQL's DO $$ ... $$ LANGUAGE plpgsql
block + JWT config + SET LOCAL
. MySQL / SQLite / MongoDB each have their own stored-procedure / migration-test concepts, but with different syntax and portability (see cross-database mapping below).
"My environment hits all the conditions" decomposes into 5 dimensions. Each dimension has its own marginal-value curve for the combined offense + defense pattern.
| Size | Offense applicable? | Defense applicable? | Why |
|---|---|---|---|
| Solo developer | ✅ Strongly recommended | ✅ Strongly recommended | Zero external correction force; engineering means is the only remedy |
| 2-3 small team | ✅ Recommended | ✅ Recommended | Before code review culture forms, similar to solo |
| 4-10 team | ⚠️ Evaluate | ✅ Recommended | Code review partly plays the attack role, but reviews do not actively audit |
| 10+ organization | ⚠️ Evaluate | ⚠️ Evaluate | Multi-tier review + QA + senior dev pings, governance rule marginal returns diminish |
10+ organizations are not "cannot use", but "ROI becomes hard to calculate". Yet piece 1 (Registry markdown) and piece 8 (Iteration log) remain applicable. These two are for "organizational memory", independent of team size.
| Horizon | Offense applicable? | Defense applicable? | Why |
|---|---|---|---|
| < 1 month (hackathon / spike) | ❌ | ❌ | Forgetting "3 months later" does not exist; pinning via commit message is sufficient |
| 1-3 months (early MVP) | ❌ | ⚠️ Evaluate | Business contract not stable; frequent trace breaks drag iteration |
| 3-12 months (growth phase) | ⚠️ Evaluate | ✅ Recommended | Cross-layer bug experience accumulating; pick 2-3 painful traces to lock first |
| 12+ months (long-term maintenance) | ✅ Strongly recommended | ✅ Strongly recommended | "Forgetting 3 months later" cost fully visible |
My environment (24+ months maintenance) hits the strongly recommended region.
"Cross-layer dependency" definition: a piece of data flowing from DB to UI through N transformation points (trigger / RPC / store / composable / component / helper).
| Depth | Offense applicable? | Defense applicable? |
|---|---|---|
| ≤ 2 layers (DB → UI direct) | ❌ | ❌ |
| 3-5 layers (with store + composable) | ⚠️ Evaluate | ✅ Recommended |
| 6+ layers (with trigger + RPC + helper + ACL + multiple components) | ✅ Strongly recommended | ✅ Strongly recommended |
My environment (e-commerce + inventory + roasting + POS + multiple RLS policies) sits at roughly 6-9 layers per business chain.
| Change frequency | Offense applicable? | Defense applicable? |
|---|---|---|
| Weekly algorithm change | ❌ | ❌ |
| Monthly 1-2 changes | ⚠️ Evaluate | ⚠️ Evaluate |
| Quarterly 0-1 change | ✅ | ✅ |
| Yearly stable | ✅ Strongly recommended | ✅ Strongly recommended |
When business contracts churn often, pinning becomes a burden (every change requires updating trace test + registry + iteration log).
| Intensity | Offense applicable? | Defense applicable? |
|---|---|---|
| Never use AI | ✅ but piece 5 unused | ✅ but piece 5 unused |
| Occasional (few times a week) | ✅ Recommended | ✅ Strongly recommended |
| Heavy (daily main driver) | ✅ Strongly recommended | ✅ Strongly recommended |
When AI pair-programming is heavy, piece 5 (AI reminder skill) provides the highest value because AI lacks the "I edited X last week" muscle memory; every new conversation starts from zero.
"Objective" vs "subjective" is my own coarse project classification (working name, my own placeholder term).
The two project classes have very different applicability profiles.
| Piece | Applicability for objective projects | Why |
|---|---|---|
| 1 Registry / 2 Trace test / 3-4 Governance rule | ✅ High | "Right / wrong" has explicit oracle (queryable from DB, expressible as spec) |
| 6 Pure-function helper | ✅ High | Business logic expressible as pure function (e.g. "annual threshold → tier") |
| 7 Caller exemption | ✅ High | Thin wrapper scenarios common |
| 8 Iteration log | ✅ High | Decisions like "why cash-first not bonus-first" need recording |
| 9 Reverse verification | ✅ High | Breaking the anchor produces a clear expected red |
| 10 sql-only-trace | ✅ High | Useful when DB logic is dense |
| 11 Business contract freezing | ✅ High | "Current behavior" is definable |
The combined pattern fits as a whole set. My environment is objective.
| Piece | Applicability for subjective projects | Why |
|---|---|---|
| 1 Registry / 2 Trace test | ⚠️ Partial | No clear "right / wrong" oracle; pinning does not land |
| 3-4 Governance rule | ⚠️ Partial | Can pin "structure" (helper must exist) but not "content" |
| 6 Pure-function helper | ✅ | But helper itself is a suggested value, not a SSOT |
| 7 Caller exemption | ✅ | Same applicability as objective |
| 8 Iteration log | ✅ | "Why this copy revision" decisions still valuable |
| 9 Reverse verification | ❌ | Breaking the anchor does not necessarily produce red (no clear oracle) |
| 10 sql-only-trace | ❌ | Subjective projects usually do not use DB logic |
| 11 Business contract freezing | ⚠️ Partial | "Contract" concept on subjective side is closer to "style guide" |
Subjective projects typically use 5-6 of the 11 pieces. A rubric-driven workflow + iteration log fits better than pinning test + governance rule.
Many projects are hybrid. Examples:
Hybrid projects use "zoned governance": objective zones get the full combined set, subjective zones get rubric + iteration log.
Why does AI pair-programming need trace lock more? Four structural differences.
A traditional developer who has spent 6 months in a codebase has "if I change X, also touch Y" baked into muscle memory. Grep is no longer needed every time; past pitfalls are avoided instinctively.
An AI agent enters every new conversation with empty context. A bug fixed last week is rediscovered from symptom-grep this week. Institutional memory does not exist at all.
Trace lock externalizes muscle memory into AI-readable artifacts (registry markdown + skill auto-trigger), so each new conversation inherits the previous one's "muscle memory" directly.
Traditional teams have Slack threads, code review comments, standups. A senior dev seeing a PR will proactively ping "remember to also update Y after editing X".
AI has no senior dev on Slack. Governance rule + skill auto-trigger is the engineering means of supplying the "senior dev on Slack" role.
A traditional developer does not "forget" after reading the codebase. An AI agent's context window has a hard cap (~200k tokens); long conversations drop early decisions.
Iteration log + registry externalize decisions into markdown, so the next conversation reloads from markdown.
When AI sees a red test, the instinct is to edit the test (turn it green) rather than ask "why was this test written this way".
Business contract freezing (piece 11) + a // Why: contract pinned after last week's bug; read incident pinning case before editing
comment inside the trace test is what blocks the instinct. Without that comment, AI two turns later will flip expect(x).toBe(true)
to expect(x).toBe(false)
because "the test was red".
AI pair-programming pain → Combined-pattern piece
Unaware of N cross-layer rels → Offensive audit + piece 1 Registry
Unaware editing X breaks Y → Piece 2 Trace test + piece 5 skill auto-trigger
Internal helper edit unblocked → Piece 3-4 Governance rule
Unsure why this was written → Piece 8 Iteration log + piece 11 Decision Pinning
Red test → edit the test → Piece 11 + trace test's incident pinning comment
Every pain point has a corresponding piece.
When porting pieces to a different stack, the skeleton stays but the implementation gets swapped.
| Source (Vitest) | Target framework | Main replacement |
|---|---|---|
describe / it / expect |
||
| Jest | Same, near-zero edits | |
describe / it / expect |
||
| Mocha + Chai | ||
expect(x).toBe(y) → expect(x).to.equal(y) |
||
describe / it / expect |
||
| Pytest | ||
def test_xxx(): + assert x == y |
||
describe / it / expect |
||
| RSpec | describe "x" do; it "..." do; expect(x).to eq(y); end; end |
|
describe / it / expect |
||
| Go testing | ||
func TestXxx(t *testing.T) + if x != y { t.Errorf(...) } |
||
The 5-section structure (imports anchor / setup current state / assert behavior / future regression catch / why-comment) is framework-independent.
| Source (Node.js) | Target | Main replacement |
|---|---|---|
fs.readFileSync + /regex/ |
||
| Python | ||
open().read() + re.compile(...) |
||
| Node script | Ruby rake task | |
Rake::Task + File.read + Regexp |
||
| Node script | bash + grep / awk | Feasible but regex syntax inconsistent; recommend ripgrep + logic layer in bash |
| Node script | Go binary | |
os.ReadFile + regexp.MustCompile |
||
CI integration: every stack supports pre-push hook (Husky / pre-commit / lefthook) + GitHub Actions / GitLab CI.
| Source | Target | Replacement |
|---|---|---|
JS // @xxx-ok: reason |
||
| Python | ||
# noqa: xxx-ok reason (or custom) |
||
| JS | Go | |
//go:build xxx-ok or custom build tag |
||
| JS | Ruby | |
# rubocop:disable Style/Xxx style |
The key: the rule is "a comment containing the xxx-ok token is recognized by the governance rule as a valid bypass", language-independent.
This is the most stack-specific piece.
| Database | Corresponding mechanism | Main difference |
|---|---|---|
| PostgreSQL | ||
DO $$ ... $$ LANGUAGE plpgsql block |
||
| My environment, full support | ||
| MySQL | ||
DELIMITER // PROCEDURE ... // + manual CALL |
||
| No DO block; needs CREATE PROCEDURE + CALL two-step | ||
| SQLite | No stored procedure; use BEGIN TRANSACTION + application-layer driver | Most restricted |
| MongoDB | No SQL; use aggregation pipeline or mongosh script | Different paradigm entirely |
| Snowflake / BigQuery | Stored procedures exist, syntax differs | Cloud DW; CI integration harder |
The SET LOCAL
mechanism (RLS JWT simulation) is PostgreSQL-specific. MySQL / SQLite have no equivalent; you must test through the application layer or bypass RLS.
If your stack is not PostgreSQL, downgrade piece 10 to "application-layer integration test" (run tests via Node / Python / Ruby code connecting to the DB). The skeleton stays "SEED / RUN / ASSERTIONS / CLEANUP" but sits in the application layer instead of SQL.
A2 line 327-337 lists 5 cases (against pieces 1-5); B2 line 650-660 lists 5 cases (against pieces 6-11). Merging, deduplicating, and adding fresh cases gives 8.
Forgetting "3 months later" does not exist; pinning via commit message + PR description is sufficient. The setup cost of the combined pattern (A2 takes about 3-4h, B2's first gap takes 6-9h) exceeds the entire short-project development time.
Writing to commit message or PR description is enough; building a registry is over-engineering. The offensive audit also will not reach N BLOCKER (no N traces to find), so ROI does not justify the work.
If the team lives in Notion / Confluence, syncing git and wiki in parallel becomes a drag. Piece 1 (Registry) and piece 8 (Iteration log) both assume markdown is first-class; moving them to Notion / Confluence is infeasible (no git diff, no CI integration).
Pieces 3-4 (Governance rule) depend on pre-push hook or CI enforcement. If the CI pipeline cannot accept custom Node / Python scripts, governance rules have nowhere to attach and slowly drift to "ignored".
Piece 5 (AI reminder skill) targets the integration points of Claude Code / Cursor and similar tools. Without such a tool the skill has nowhere to attach. The pattern drops to "9 applicable pieces" and still works, but loses the "auto-trigger" key property.
In scenarios where helper algorithms change weekly, trace test pinning becomes a drag. Stabilize business first, then lock. This is dimension 4's "weekly change" case.
Traditional code review already plays part of the governance role. The combined pattern still works but with diminishing marginal returns, so ROI needs evaluation. This is dimension 1's 10+ organization case.
That said, piece 1 Registry + piece 8 Iteration log remain applicable (for organizational memory), and can be adopted standalone.
Two C1 cases:
Suppose I take on a contract and want to apply the combined pattern to a new Vue + Supabase project (same stack).
| Phase | Estimated time | Content |
|---|---|---|
| 1. Copy 9 framework-layer pieces | 1h | Copy governance-guard.mjs / .claude/skills/ / registry markdown template / iteration log template |
| 2. Update paths and env vars | 0.5h | repoRoot logic / registry path / trace test directory |
| 3. Write first trace (client-specific) | 1-1.5h | Run 5-step audit + write registry block + trace test |
| 4. Write first helper (business-specific) | 1-2h | Extract pure-function logic from scattered callers |
| 5. CI / pre-push hook integration | 0.5h | Add governance-guard.mjs to hook |
| 6. Write the matching CLAUDE.md rule | 0.5h | Document "this project's trace nodes are X; AI must run 5-step audit before editing" |
| Total | ||
| 4.5-6h | ||
| Includes first trace + first helper |
Each subsequent trace is roughly 30-45 min (A2 estimate); each gap fix using the 6-piece pattern is roughly 1-1.5h (B2 estimate).
Switching to a different stack (e.g. Next.js + Prisma + Jest) adds 2-3h of replacement work (trace test syntax / governance rule regex / sql-only-trace variant).
ROI break-even: in my environment it is 2-3 months (past 6 months: 5 cross-layer bugs × 3-5h = 15-25h of fixing). The break-even on a new project depends on cross-layer bug frequency: six months without a cross-layer bug is unprofitable; six months with 3+ such bugs is clearly profitable.
The order I would suggest (extending C1's suggestion with engineering details):
business-flow-audit-fix
C1's heuristic: did the past 6 months produce ≥ 3 "cross-layer contract drift" bugs? Yes → worth it. No → maybe not yet.
The engineering version adds a quantified indicator: the cumulative hours spent fixing cross-layer bugs in the past 6 months.
My own past 6 months totals about 25-30h.
I am also unsure whether this threshold transfers to your situation. But "cumulative bug-fix hours" is a more honest signal than "count" (5 small bugs differ from 1 big bug).
This post is an organized record of conversations I had with Claude (an AI pair-programming tool) during May 2026. I noticed some patterns worth keeping for my own future reference, so I asked Claude to help structure them into writing.
A few things I'm not claiming:
If a professional engineer spots misuse, or there's already a more standard name for any of these concepts, I genuinely welcome corrections.
本文原載於我的部落格： Combined Offense + Defense (Engineering Edition) — Cross-Project Reuse Matrix and When Not to Use