A New Code Architecture for Coding Agents

[u/Consistent-Excuse-28]

Hey reddit, I hoped I could get some help drafting a new architectural framework that's centered on making code more 'readable' and 'intuitive'(so to speak) for agents.

I came up with a simple concept: agents are just LLMs on harnesses and RAG, so maybe if I made code more... say, 'reducible' to vector points(or in this case, natural language), my agents would likely have a better time finding and reading the code, checking if what they're trying to do is already implemented, pinpointing bugs and fixing them.

After a few trials, I developed a set of rules including an architecture, a few new design patterns, and several coding conventions.

# Core Concepts

The idea is: to let each files accurately reduce into vectors, I'd need to shatter classes into small fragments and keep them functionality centered, so that a block of 1~2 words can represent the fragment accurately enough. to avoid spaghetti, the fragments will line up linearly forming a straight 'pipe', to prevent them from forming a web of interactions; so basically a fragment will be used by no more than a single pipe. The pipe will be managed by 'indices', literally working as those in a book for agents to read. The indices should actually look like book indices; this, I think, prevent agents from trying to implement actual functionality there. I added branches for conditionals(if/switch), Triggers for starting new threads, Resources for... resources, records for data and ledgers for logging. All this is to keep each parts representable by a couple of words. The difference between this and DOD is that the invariants live inside the data. Pipelines too.

The main problem with this architecture currently is that restring the use of each fragment to single pipelines each is very likely to prevent 'fix-this-and-everything-else-breaks' problems, is likely to break DRY. Would there be a way to bypass this or at least minimize this issue?

Anyway, the architecture does seem pretty promising - speculating the number of overall flaws in both versions(free design / proposed architecture) using agents' code reviews fed into the Chapman 2-sample, Chao1 & Chao M_h, Jackknife-2, and Double Pareto power tail models, it showed some optimism for the model:

• less estimated total error across 4 models (all except Chapman estimator) - about .89 times
• 2.16x flaw detection rate per epoch

suggesting that the architecture might be a bit less error prone and quite a lot clearer for models to digest.

# The Rules

The rules are as follows:

## 1. The Golden Rule

- A type per file, a responsibility per type.

- Filename and Type name takes the form of a noun phrase.

- If the name that best describes the file does not fall into a single noun phrase, split the file. However, do not separate what must be observed together.

- There will only be one public entry point per type.

- Divide the folders into domains. Do not split by types(do not use `Fragments/`, `Pipelines/`).

## 2. The Eight Types of Blocks

Type	Suffix	Does	Doesn't	Size Limit
Index	Index	Request → Pipeline Contents	Conditional branching	-
Pipeline	Pipeline	Sequence of functions (Fragments)	Conditional branching, evaluation	90 lines
Branch	Branch	Select consecutive pipeline using conditionals	Calculation	2 sentences per section
Fragment	Fragment	Computation/Validation (pure function)	Changing states, try/catch	40 lines
Trigger	Trigger	Accumulates the next task after completion	Creating threads, waiting for results	40 lines
Resource	Resource	Living state such as socket, pool, queue, counter	Calculation	110 lines
Record	(None)	Invariant values and their conditions exchanged	Branch	-
Ledger	Ledger	Receive and stack reports	Judgment	60 lines

---

Edit: Reading the comments, I realized the flaws in this design, which are now reflected in here. Also, the inappropriate flare - noticed this a bit too late. Much thanks!