Jin's Architecture Gate: Approve the Plan, Not the Diff
Adding an "Architecture Gate" to Coding Agents: How Jin Achieves "Review Architecture First, Then Write Code, No Drift"
This is a core design breakdown of Jin (an architecture-first desktop coding agent). No model hype, just engineering.
0. The Problem: Why "write-code-first" agents make people afraid to use them in production
Tools like Codex / OpenCode / Claude Code follow this workflow:
requirement → model calls tools (read file/write code/run tests) → spits out a diff → you review → merge
The pain points concentrate in the last two steps: the bigger the diff, the more expensive the review; if the review is never complete, you never dare to merge; if you never merge, no one dares to go all-in on a real project. Additionally, the model can easily "drift" along the way — adding things not requested, changing places not authorized, forgetting the original intent.
Jin's approach moves the gate forward to the "intent/architecture layer" rather than the "code layer":
requirement → model produces an [architecture change proposal] → human reviews the proposal (approve/reject) → only then implementation is allowed → automatic verification + self-repair → versioning
Below, each key implementation is explained.
1. Architecture Ledger: Turning "what this project looks like" into queryable facts
When Jin starts, it scans the codebase and builds a graph of L0 (package/directory) / L1 (module) / facet (responsibility surface), plus symbol definitions obtained from LSP, persisted as a snapshot.
Its role is not "display" but implementation boundary constraints:
- Each op in a proposal references a node in the ledger (
node.add/node.update/node.remove). - During implementation, the model can only modify the
filewhitelist approved in the proposal. Going out of bounds → the tool layer directly rejects it.
This already suppresses half of the drift: the model has no chance to touch anything outside the approved scope.
2. Proposal = What You Review (not a diff)
When a requirement comes in, the planner does not produce code but a JSON structure:
kind: plan,title / goal / messagetasks[]: each task hasfiles[],acceptance[](acceptance criteria),dependsOnnodeIntents[]: which L1/facet nodes will be touched this timeops[]: structural changes (add/update/delete node/edge)
In the UI, you look at this proposal + its impact surface, not hundreds of lines of diff. Only after approval does it enter implementation.
Key point: acceptance criteria are written in natural language; after implementation, there is an acceptance review step — the model checks item by item whether the code satisfies "the effect you originally wanted." This is the automatic safety net for "intent consistency."
3. Symbol-Level Context: Don't Feed the Whole Repository to the Model
This is what I consider the most valuable part. Traditional agents (OpenCode/Codex) use either whole files or rely on the model to grep while implementing. Jin's approach:
// Use the LSP symbol index to take only the 40 lines before and after the symbol to be touched
for (const path of wantedPaths) {
const symbols = lspSymbols.filter(s => s.path === path);
body = symbols.map(s => slice(lines, s.line - 40, s.line + 40)).mergeOverlaps();
}
wantedPathsis derived from the architecture ledger (thenode.filein ops + nodeIntents + reuse candidates).- When a node has no
filewritten, use the LSP symbol name to reverse-look up the file where the definition lives; only if not found do you suggest "use grep/glob to locate." - Existing LSP errors/warnings in the target files are also appended to the end of the prompt: "There are already problems here; fix them along the way."
Effect: the model does not see an 800-line whole file (of which 700 lines are irrelevant), but rather "precisely relevant symbol blocks + known issues to fix." Tokens are saved, drift is reduced, and existing bugs get fixed as a bonus.
4. Implementation Loop: Write Code → Run Checks → Self-Repair on Failure
Implementation uses the Eko engine (an agent runtime with a tool loop). What Jin does inside runEkoCoder:
- Toolset:
read_file / write_file / apply_patch / run_shell / delete_file(all are staging-style, entering a virtual workspace first and landing on disk only after approval) plusgrep / glob / search_code(RAG) / architecture / todo_write / view_image / fetch_url / web_search / mcp__*. - Context: the symbol-level relevant code from point 3 above.
- Before wrapping up: the agent proactively calls
run_checks(runs the project's owntest/typecheck/lint). - Failure feedback: After implementation, Jin runs
runProjectChecksagain; any failures are fed back to Eko for one self-repair round, then re-run. - Consistency verification: re-scan the codebase to check whether the approved architecture actually landed (whether node/facet are in place, whether files appear).
In other words, "writing code correctly" does not depend on model self-discipline, but on automatic checks + failure self-repair + consistency verification — three layers.
5. Versioning and Rollback: Making "changes" reversible
- Each implementation is a WAL version, replayable, diffable between two versions, and replayable.
- Before implementation,
git stash createcreates a dangling commit as a checkpoint; "undo this round" in the UI =git restore --source=<checkpoint>, without touching HEAD. - Dangerous operations (deleting files, rewriting git history, piping remote scripts) have a blacklist at the shell layer plus auditing (
.jin/cache/shell-audit.jsonl).
6. Context Management: Compression like Codex, but with an Extra "Local Trimming"
Long sessions will blow up the context. Jin's compression strategy (compactionMode):
- trim (local pruning, no model): by rounds, cut old messages into "user request original text + assistant conclusion tail," discarding intermediate reasoning/tool noise. Instant, offline, deterministic.
- llm (summarization): let the model write the old half into a structured handoff (Goal/Decisions/Work/Open questions/Next steps).
- auto (default): first trim; only if still over budget escalate to llm; if llm fails, fall back to trim automatically.
Threshold = context window × compression ratio × 0.45 (the architecture prompt itself takes a large share, so compress early).
7. Other Engineering Details (One-Line Version)
- Multi-provider: OpenAI Chat/Responses, Anthropic Messages, Gemini
generateContent, Ollama. The model preset table automatically carries context window/price/vision. - MCP:
tools/listmetadata goes into the tool table (mcp__server__tool), results are serialized as text, everything goes through auditing. - AGENTS.md: project-level and global two layers, planning/implementation prompts auto-injected, takes effect immediately upon change.
- Hooks:
.jin/hooks.jsonhaspreToolUse(can intercept)/postToolUse(audit)/beforeImplement;.jin/commands/*.mdfor custom slash commands. - LLM diagnostic logs: JSONL + console, recording empty streams, unsupported tools, HTTP degradation — no guessing when troubleshooting.
8. What Really Differs from "Bare OpenCode/Codex"
It's not "one more tool," it's an extra gate + a set of boundary constraints:
| OpenCode / Codex | Jin | |
|---|---|---|
| Review object | Code diff | Architecture proposal (impact surface) |
| Drift control | Model self-discipline + your review | Whitelist rejection on out-of-bounds + consistency verification |
| Context | Whole repo / model self-grep | LSP symbol-level + existing diagnostics |
| Correctness safety net | Run tests (manual/tool) | Automatic checks + self-repair + consistency verification |
| Reversibility | git (you manually) | WAL versions + checkpoint one-click undo |
One-line summary: Jin does not have you review code; it has you review intent; correctness is left to the automatic loop.
9. Applicability Boundaries
- Suitable for: medium-to-large, multi-module projects with architecture boundaries and a need for auditability; you serve as lead/architect.
- Not suitable for: one-off scripts, demos, rapid prototypes — plain Claude Code is faster.
- If you don't want to do "proposal approval" at all, Jin's core value disappears.
Open source github.com/ZYF93/Jin; PRs / brickbats welcome.
Top 1 of 2 from juejin.cn, machine-translated. The original thread is authoritative.
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?
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.