{
  "$type": "site.standard.document",
  "bskyPostRef": {
    "cid": "bafyreifsstbp2ix43vrp5pywipys24kfc747jokjh362ws7csfcvhmazly",
    "uri": "at://did:plc:lk3jfj3zq4k4wxnk474axylu/app.bsky.feed.post/3mp463ajpidg2"
  },
  "path": "/t/software-architecture-is-fractal-read-only-if-youre-bored/1384155?page=2#post_40",
  "publishedAt": "2026-06-25T09:10:27.000Z",
  "site": "https://community.openai.com",
  "tags": [
    "@drmanoj4u",
    "github.com",
    "GitHub - TechSpokes/agency-specifications-files-agents-md: AGENTS.md file guidelines",
    "GitHub - TechSpokes/agency-specifications-files-readme-md: Readme.md Specification",
    "gist.github.com",
    "https://gist.github.com/sergeliatko/2e3f2a165797db81337c598e9f5f2c53",
    "show original"
  ],
  "textContent": "@drmanoj4u thanks for the replies. They are useful perspectives.\n\nHowever I think I have not managed to explain the background for this approach.\n\nFirst of all I don’t think code is the source of truth any more, at least not in this system I am trying to explain. What I think is more this:\n\nCode is just a projection of the architecture and code can be the source of truth for only “what is currently implemented”.\n\nThe architecture is something abstract and basically it represents the system as an abstract agglomeration of requirements, intents, connections, and all other bunch of things, which we could call the “knowledge about the system”. The files I suggest for architecture are also just a projection of that knowledge.\n\nNow the architecture itself is just a projection of how the software architect thinks about solving that particular problem (what problem software solves).\n\nBut here is the trick. Those thoughts about how to solve a problem are just a projection of the architect’s vision of the world and how the world works. In most cases that vision is based on a system of beliefs the architect carries in their mind. So even that vision is just a projection.\n\nThe true problem is humans do not like questioning their own system of beliefs because they are too much attached to it. Questioning it makes them feel attacked by the question so they protect because they think that’s what they are.\n\nBut if you look carefully into the system of beliefs, most of it is just a bunch of crap contradicting itself, pulled from various third-party claims coming from: your parents, your friends, your school, your university, YouTube, forums, church, government, and so on.\n\nSo to solve the code problem we need to go back up to that system of beliefs (and make systems that will) challenge those beliefs, remove conflicts, align everything, and then project a better vision of the world. This will result in a better vision of how to solve a problem, and a better vision of the architecture, which will result in a better code (as a projection of it).\n\nBut that is not the scope of this test project. Here the scope is to be able to detect the drift of the architecture itself (or ots projection written in *.architecture.yaml files).\n\nDrift detection is a part of reasoning about the architecture and fractality is what allows for simplifying the reasoning logic/code by making the elements on every level be similar in shape so that the reasoner can operate effectively on every level.\n\nThis is how a unit is born in this system. The concept of unit should be seen as the interface between the element in the system and the reasoner operating on the architecture. Being standard across all levels and all system elements, UNIT allows reasoner simplification.\n\nNow after some thoughts on that interface, I see that it has three aspects:\n\n  1. What the element is. This is what I call the “essence”.\n  2. How you interact with this element, which is the “behaviour”.\n  3. What this unit requires to survive in the system and what it provides to the system which is the “context”.\n\n\n\nThis is how those three contracts were born. They basically describe the three aspects of the unit.\n\nNow there is another axis on which we can analyze the unit is the outside surface and the inside surface.\n\nThe outside surface is the trinity of those three aspects but the inside surface is the system inside the unit. That should be described separately and differently from the unit’s outside surface because that inner environment may have its own reasoning. It is there to define the rules for the inner units. This is how the “environment” is born in this system.\n\nNow the intent: The Why. What you saw as Why on the previous versions was just for quick testing. Realistically that Why is split into the purpose and reason, where purpose explains the goal and reason traces the basis for the decisions. You need to capture that because this is basically what every (most of) software documentation is lacking and which creates the drift in the code or “staleness” of the code as a projection of the architecture.\n\nThat intent cannot stand in a stand-alone file for that exact reason that that file would be different from unit description. The intent has three aspects, same as unit:\n\n  1. What is the intent for unit creation that goes into the purpose and reason on the essence contract\n  2. What is the intent for the unit behavior that goes into the behavior contract\n  3. What is the intent of the unit inside its environment, which goes into the context contract\n\n\n\nThis is what allows the intent locality inside the architecture file describing the unit.\n\nNow let’s talk about that **locality** , which will explain why I’ve chosen to put the architecture as a stand-alone file next to the code.\n\nTo get the background for that, here are three links which will paint the decor:\n\ngithub.com\n\n### GitHub - TechSpokes/agency-specifications-files-agents-md: AGENTS.md file guidelines\n\nAGENTS.md file guidelines\n\ngithub.com\n\n### GitHub - TechSpokes/agency-specifications-files-readme-md: Readme.md Specification\n\nReadme.md Specification\n\ngist.github.com\n\n#### https://gist.github.com/sergeliatko/2e3f2a165797db81337c598e9f5f2c53\n\n##### code-commenting-specification-v2.md\n\n\n    # Code Commenting Specification\n\n    Version 2.0.0\n\n    A specification for code commenting in multi-entity codebases where humans, AI agents, and automated tools collaborate.\n\n    ## 1. Abstract\n\n    This specification defines principles, a tag vocabulary, requirement levels, and guidelines for code comments in software projects. It treats code comments as a form of cross-intelligence context transfer: persistent, asynchronous messages embedded in source code that carry information not available from the code itself.\n\n\nThis file has been truncated. show original\n\nAll those three were derived from the pet theory I have under the code name “The 3-Body Problem: Cross-Intelligence Communication”. Where basically humans, AIs, and workspace tools operate in a shared file system, resolving a problem. All three “minds” have their own biases and limitations; so the theory basically lays this down in a simpler manner, explaining how to compensate for each of the limitations. (Not yet public).\n\nThe locality and readability are needed in modern software projects to allow humans, workspace tools, and AIs to have the architecture files handy next to the code so that it’s harder to skip them. That’s why placing them somewhere in the docs will increase the chances your architecture documentation and code will go out of sync.\n\nHere is a quick example. Pull a diff on your code. Use a simple rule to derive the architecture file names from the code file names and then check the diff on architecture files to see if the list of modified files matches. A simple command may tell your agent something like: “Hey you modified the code. Please check why you have not modified the architecture. If you are modifying the architecture, please make sure the reason is properly reflected in the documentation and is traceable for future agents working in this space.” And some other variants of that depending on how you approach your software building process.\n\nPersonally, I don’t write code anymore. I don’t review code anymore. What I care about is how well my intent is expressed, so that the agent can lock that intent by tests, designing the test suite which will cover the aspects my architecture enforces, so that at the end of the session, the agent may run a CLI tool which will point the agent to the areas it has missed.\n\nI don’t write documentation either. Agents are great for that. What I need to do is to give them enough context and a process with values and goals I want to survive in a system so that they are able to write the documentation way better than I would do, even in my dreams.\n\nIn 2026 most of the code is either generated by a system or by AI. So if the architecture has changed, it is very easy to tell the agent: “Check the changes in the architecture and update the code so that it correctly reflects those changes.”\n\nThe biggest problem is the implied knowledge humans carry in their head and never put somewhere where the agents and tools can read that intent. That is basically coming from two reasons:\n\n  1. The first one: an experienced architect considers that so obvious that it is not even worth mentioning.\n  2. The second one is that there is no easy system to describe architecture in a simple way so that agents can understand it.\n\n\n\nThis is why I ended up with YAML files. That’s the only format I know of which is easily readable by humans and AIs (and is cheaper in tokens than JSON) and can be read as structure by workspace tools (with some workarounds, as I’ve not yet found terminal native tools to navigate inside the objects written in yaml as one can do in JSON).\n\nSo if we take the architecture of the software as a process of:\n\n  1. querying your beliefs to understand how you would approach problem-solving\n  2. converting that into an architecture for the software\n  3. drafting this software (or scaffolding the software as an architected system)\n  4. projecting that into the tests first and code second\n  5. compiling and run the tests to understand if your code is a correct projection of your architecture\n\n\n\nThen writing the architecture as stand-alone files in the same source folder as the code before writing the code is a great approach because it gives you the ability to scaffold the repository using pseudo code described in those files (unit contracts force agents to write interfaces first, which is very similar to the test-driven development. Environment and unit descriptions force agents to write tests to protect the behavior and the contracts, which gives you the test-driven development at the same time). Everything is local and well organized even before you start writing your code.\n\nThen you write the code and see if that code works the way you want.\n\nAnd here by “you write” I mean “you create the environment for the agent to do that on your behalf.”\n\nSo the whole system here is not written for humans in most of its parts. It is written for AI’s. The only thing where humans are involved is properly expressing their intent and their vision of architecture, which can be then projected into those *.architecture.yaml files. And those files capture way more implied knowledge than any documentation I see so far. And they are next to the code so that when your agent reads the folder, they are just sitting above the code file in the folder list output and are harder to miss than some *.md file in docs/.\n\nCurrently this thing is still in the phase of tests and proof-of-concept. Ideally it will leverage code queries, graph databases, semantic reasoning, and some LLM automations so that you have it somewhere as a binary running, accessible through CLI or MCP for agents and workspace tools to use as both a planning tool and a revision tool. Potentially with an graphical interface for humans to review the architecture.\n\nBut we are not there yet.",
  "title": "Software Architecture Is Fractal (read only if you're bored)"
}