Series 01 — The real problem

A spec gives a junior a checklist, not judgment.

He shipped in a day because the agent is fast. Two weeks later the work came back, because the project lived in someone else's head.

01 — The scene

He had a feature by the end of the day

A junior joins a team that has used an agent for months. Within a day he has a feature. Two weeks later the feature is reverted, the tests are green and still wrong, and nobody can say why.

The easy explanation is that he is too junior. The truer one is that he was handed a task, a repository and a model, and nothing else. He did not know which decisions were already settled, which tables nobody was allowed to touch, or which pattern the team had already rejected. So he guessed. The agent guessed with him.

This is not a story about a bad junior. It is a story about a project that was never written down. He was fast because the agent is fast. He was wrong because the context was thin.

Want to see what this looks like in your project? Book a 30-minute pilot call.

02 — Why SDD does not save him

A spec holds the work. It does not decide it.

Spec Driven Development is a real improvement, and it is not enough. It changes the order: write the spec first, break it into tasks, build against it. It makes the developer say what they intend before the model starts typing.

A spec answers one question. What are we building now? It does not answer the questions that decide whether the result belongs in this project. Which decisions are already made, and why? What is forbidden here, even if it would work?

A junior can write a clean spec and still make a call a senior would never make. The spec is a container. What goes in it depends on what the junior already knows. SDD puts the input in order. It does not hand over judgment.

Teams adopt SDD and the work stays unpredictable. You can see the method. You cannot see the missing context until something breaks.

03 — What a project OS is

Write down how this project actually works

A project OS is not a methodology, and it is not a tool. It is the set of documents that describe how this project works, written where a person and an agent can both read them.

The order is the point. Requirements before architecture. Architecture before standards. Standards before the plan. It is the path a competent team already walks, written down instead of remembered. Models read it without special training, across providers. That written path is the fingerprint.

You do not hand a new hire a methodology on the first morning. You show them where the truth is: the docs, the decisions, the history. Then you give them work with a boundary and a reviewer. A model needs the same welcome.

OrkAI keeps this project knowledge available. Woky uses it to coordinate real engineering work.

04 — What the OS gives the junior

Four questions, answered before anyone is interrupted

A CTO I know well runs engineering at an early-stage startup, with a team in South America and five juniors hired to keep the cost down. Day to day he was the principal architect and the principal engineer. He wrote more code than anyone, reviewed everything, trained the juniors, and worked more than twelve hours a day. The project lived in his head. One junior he trusted carried more of it than the rest. There were no requirements, no architecture and no standards a newcomer could read. Every question went to the same person, who was already the bottleneck.

In July they put the project’s OS to work. The team did not change. Neither did the model or the editor: DeepSeek through Cline for the day-to-day work, GLM 5.2 and 5.3 for planning. The project simply had its fingerprint loaded, and the juniors could read it.

They stopped asking him about the project. The junior he trusted now leads the other four and covers DevOps. The CTO stopped working more than twelve hours a day at that startup, and got time back for his own consulting. The CEO, who does not know the system exists, called the team very fast, with very good visual design, and gave the credit to the AI. He was half right. The AI was already there. The result changed when the project stopped living in the CTO’s head.

What this case does not prove: one case, not a sample. No hours before and after, no controlled comparison. The CEO sees the team, not the OS. That is evidence of what he perceived, not of what caused it.

05 — What the leader configures

He stopped being the person every question had to pass through

The leader’s job changes. It does not disappear. Before, the CTO was the routing layer: every question, every review, every decision passed through him. After, he sets up the cycle — requirement, architecture, standards, plan, milestone, task — decides where the work has to stop for a yes, and decides what the system will not allow. He updates the fingerprint when something critical changes. He is still the principal architect. The mechanical work that ate his day moves to the system and the team.

An OS without a leader is a folder nobody maintains. The leader keeps the map honest, and decides which questions deserve a new rule.

Onboarding changes with it. A junior no longer learns the project by interrupting the person who knows it. He learns how each existing thing was built, from the document that produced it.

06 — The objection that deserves an answer

Does the writing do the thinking for him?

If the OS tells the junior everything, he never grows judgment. He becomes an operator of someone else’s decisions. That risk is real. Context does not cause it. Context without reasons does.

The OS does not tell him what to decide. It shows what was already decided, and why. That is how a junior learns on a good team: beside a senior, watching a decision get made, hearing the trade-off, then making the next one. The document is the senior’s reasoning, written down. Take it away and you do not get judgment. You get guessing.

The junior with the most judgment was not flattened. He became the lead of the other four and took on DevOps. A system that turns people into operators produces a queue, not a lead.

It goes wrong when a leader writes a rule for everything, approves nothing, and calls that an operating system. If the document explains a decision, it builds judgment. If it only records a permission, it builds dependence.

07 — The decision

Hire juniors with the project written down and a leader above them. Do not hire them and hope a stricter method will stand in for the experience they do not have yet.

You are selling cheap juniors instead of seniors.

No. The CTO is still the principal architect. The OS took the mechanical work, not the architect. A junior with an OS is not a senior. He can be trusted with more, sooner.

With an OS the junior becomes an operator who does not think.

An operator is what you get from a checklist with no reasons. The OS carries the reasons, and a record. The junior who now leads the other four is the counterexample.

None of this is written down in my project.

It was not written down here either. It lived in the CTO's head. Writing it down is the first week of the pilot, not a ticket you have to buy before you start.

Explore Woky with your engineering workflow.

Start with a 30-minute conversation. Together, we will identify whether an Executive Sandbox or a Technical Pilot is the right next step.

Book a 30-minute pilot call
Marco

Founder of Woky. Twenty-five years in software. Operations for 2 million users and 50 million in transactions. Architect, engineering manager, consultant. LinkedIn · woky.dev

All posts