跪拜 Guibai
← All articles
Frontend · Backend · Agent

Jin's Architecture Gate: Approve the Plan, Not the Diff

By 张一凡93 ·
Read original on juejin.cn ↗ Google Translate ↗ Alt translation

Reviewing a plan instead of a diff cuts the review cost that keeps coding agents out of production, and the whitelist turns drift control from a model's good behavior into a tool-enforced rule. This is a workflow change that could make agents safe enough for production repos.

Summary

Coding agents like Codex, OpenCode, and Claude Code produce large diffs that get expensive to review and risky to merge, and models drift by adding unrequested features or touching unauthorized files. Jin reframes the review step: instead of reviewing a diff, you review an architecture proposal. A planner turns the request into a JSON document with tasks, acceptance criteria, and structural ops, all referencing a persistent ledger of the codebase at L0 (package/directory), L1 (module), and facet (responsibility) levels.

The ledger is not for display; it's a boundary constraint. During implementation the model can only modify files that the approved proposal whitelists; out-of-bounds access is rejected at the tool layer. Context is symbol-level: LSP symbol positions pull only 40 lines around each relevant symbol, not whole files, and existing LSP errors/warnings in target files are appended as known issues to fix. Implementation runs the project's own test, typecheck, and lint tools, feeds failures back for one self-repair round, then re-runs, and finally re-scans the codebase to verify the approved architecture nodes actually landed.

Versioning uses WAL versions for replay and diff, and a git stash checkpoint lets you undo a round without touching HEAD. Context compaction offers local trim, LLM summarization, and an auto mode that falls back gracefully. The comparison table sums it up: OpenCode/Codex review diffs, rely on model discipline for drift, and leave git rollback to you; Jin reviews the proposal, enforces the whitelist, and closes the loop with checks. It's aimed at mid-to-large multi-module projects with real architecture boundaries; for one-off scripts, a plain Claude Code is faster.

Takeaways
— Jin scans the codebase into an L0/L1/facet ledger plus LSP symbol definitions, persisted as a snapshot that serves as an implementation boundary.
— Each proposal op references a ledger node, and the implementation phase is limited to an approved file whitelist; out-of-bounds access is rejected by the tool layer.
— The proposal is a JSON structure with kind, title/goal/message, tasks (each with files, acceptance criteria, dependsOn), nodeIntents, and ops; you review this instead of a diff.
— Acceptance criteria are written in natural language; an acceptance-review step checks the code against them after implementation.
— Symbol-level context slices 40 lines around each LSP symbol for wanted paths, merges overlaps, and falls back to grep/glob only when a symbol's file can't be resolved.
— Existing LSP errors/warnings in target files are appended to the prompt as known issues to fix.
— Implementation runs the project's test/typecheck/lint; on failure, the output is fed back to the agent for exactly one self-repair round before re-running.
— A consistency check re-scans the codebase after implementation to verify approved architecture nodes/edges and files actually exist.
— Each implementation is a WAL version; a git stash --create makes a checkpoint, and undo restores from it without touching HEAD.
— Dangerous shell operations (delete files, rewrite git history, pipe remote scripts) are blacklisted and audited to .jin/cache/shell-audit.jsonl.
— Context compaction has three modes: trim (local, no model), llm (structured handoff summary), and auto (trim first, escalate to llm if over budget, fallback to trim).
— Multi-provider support includes OpenAI Chat/Responses, Anthropic Messages, Gemini generateContent, and Ollama.
Conclusions

The human job shifts from diff reviewer to intent approver, a different cognitive task; the safety of the system hinges on how carefully that intent is stated, not on the model's code discipline.

Acceptance criteria are natural language, so the model still judges intent; the gate is only as reliable as the model's interpretation of those criteria, not a formal proof.

The self-repair loop is bounded to one attempt and can only fix failures the automated checks catch; semantic drift that passes tests still slips through.

Symbol-level context is a transferable technique: it uses LSP positions to solve the token-waste problem of whole-file contexts, and any agent tool could adopt it.

Concepts & terms
Architecture Ledger
A persistent graph of the codebase at L0 (packages/directories), L1 (modules), and facet (responsibility) levels, plus LSP symbol definitions. It acts as the boundary constraint for what an agent is allowed to change.
Acceptance Criteria
Natural-language verification conditions written in a proposal that the agent checks against after implementation to confirm intent consistency.
WAL version
Write-ahead-log style versioning of each implementation step, allowing replay, diff of versions, and rollback.
Symbol-level context
Using LSP symbol positions to extract only the relevant lines around each symbol (e.g., 40 lines before/after) instead of feeding whole files to the model.
Staging tools
Agent tools that write to a virtual workspace first; changes land on disk only after human approval.
From the discussion
Featured comments
组合搭配函数

Switching the review target from a few hundred lines of diff to an architecture proposal, and letting implementation touch only whitelisted files — that step I accept. The bigger the diff, the more expensive the review, and that's always been the biggest hurdle for agents going into production. But writing acceptance in natural language and having the model check against it item by item — that step I don't accept. The model is both the player and the referee; the guarantee of intent alignment ultimately still depends on it approving itself. The only things that can truly serve as a safety net are the run_checks you wrote and the consistency rescan: tests, type checks, whether the ledger nodes are in place — those are the hard guarantees. Natural-language acceptance can only be a hint, not an acceptance. In your current setup, when acceptance fails, does it kick the work back for a redo, or does it just log a warning and let it pass?

张一凡93

In the previous version, it recorded the architecture deviation and you could choose to update the architecture or re-implement it. The current version has strengthened the gate; you can only write content that corresponds to nodes under the approved architecture. Go try it and you'll see.

See top comments, translated →
Source: juejin.cn ↗ Google Translate ↗ Backup ↗