跪拜 Guibai
← Back to the summary

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:

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:

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();
}

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:

  1. 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) plus grep / glob / search_code(RAG) / architecture / todo_write / view_image / fetch_url / web_search / mcp__*.
  2. Context: the symbol-level relevant code from point 3 above.
  3. Before wrapping up: the agent proactively calls run_checks (runs the project's own test/typecheck/lint).
  4. Failure feedback: After implementation, Jin runs runProjectChecks again; any failures are fed back to Eko for one self-repair round, then re-run.
  5. 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

6. Context Management: Compression like Codex, but with an Extra "Local Trimming"

Long sessions will blow up the context. Jin's compression strategy (compactionMode):

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)

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


Open source github.com/ZYF93/Jin; PRs / brickbats welcome.

Comments

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?

张一凡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.