Architecture principles for startups: when to write them down

Why the same debates keep coming back

Startup teams often make architecture decisions out loud, then move on. One sprint, everyone agrees to keep a feature in the main app. Two sprints later, someone asks whether it should become its own service. The question sounds new, but it usually is not.

The same thing happens with smaller choices. Where should validation live? Should this data stay in Postgres? Can the team deploy on Friday? If nobody writes down the default, each new ticket can reopen an old argument.

The cost usually shows up in senior time. A founder, CTO, or staff engineer spends 20 minutes in Slack, then another 30 in a call, then reviews a pull request shaped by a half-remembered decision from last month. That hour never appears on a roadmap, but it still slows delivery.

It also breaks focus. Instead of building, people switch into debate mode. Product work pauses while the most experienced engineer explains the same tradeoffs again. Startups feel this quickly because a small group usually carries most of the technical context.

Memory does not scale, and chat threads scale even worse. Slack, email, and meeting notes collect fragments, not rules. One thread says "keep it simple and use the monolith." Another says "split by domain when needed." Both can be reasonable. Without a short written rule, people pull different answers from different moments.

A four-person team can get away with this for a while. At eight or ten people, it breaks. New hires join, contractors help for a sprint, priorities shift, and old decisions lose their shape.

A common pattern looks like this:

• The team builds payments inside the main app.
• Next month, someone wants a separate billing service.
• Later, another feature goes into the main app again.
• The team debates service boundaries from scratch.

Nobody is confused on purpose. The team just lacks a simple rule, such as: create a separate service only when you need independent scaling, a strict security boundary, or a different release cycle. Written principles save time because they stop old debates from coming back in new words.

The point where verbal rules stop working

Verbal rules work when a startup has two or three engineers who remember every past decision. That breaks faster than most founders expect. Once the team grows to five, six, or eight people, memory stops being a reliable system.

You usually notice it during onboarding. A new hire asks where a new service should live, how it should talk to the database, or how to set up local development. Someone answers in Slack. A week later, another new hire asks the same question. Then a contractor asks again because the answer was never written down in one place.

The next problem is drift. One team builds a service one way, another team picks a different pattern, and both think they are following the normal approach. Soon the codebase has different API shapes, different migration habits, and different ways to handle background jobs. None of those choices is always wrong by itself. The problem is the pileup. Every project starts to feel slightly unfamiliar.

Deployment friction is another clear sign. If one project ships through a simple pipeline, another needs manual steps, and a third depends on one engineer remembering a checklist, the team does not have shared rules. It has tribal memory.

The warning signs are usually obvious:

• Similar services get built in different ways.
• New hires ask the same setup questions again and again.
• Release days feel different across projects.
• Senior engineers settle the same debates every week.

That last point hurts the most. Senior people become human routing tables. They keep answering service, data, and deployment questions that should already have a default answer. Their time goes to tie-breaks instead of design, product risk, or customer problems.

At that stage, a short principles page is no longer a nice extra. It is a way to protect senior attention. It will not remove judgment, but it will cut a lot of repeat debate.

What to include in a short principles page

A useful principles page should answer the choices that cost the team the most time. For most startups, that means services, data, and deployment. If people can read it in ten minutes and use it the same day, it is the right size.

Start with rules for creating a new service. Say when the team can add one, when they should extend an existing app instead, and what every new service must have on day one. A rule like "no new service unless it has a clear owner, monitoring, and a reason it cannot live in the main app" cuts off a lot of vague debate.

Data rules need the same level of detail. Define where product data lives, who can create a new database or schema, and how tables, fields, events, and queues get named. Naming rules sound dull, but they prevent duplicate fields, messy joins, and long arguments six months later.

Deployment defaults matter because teams drift into one-off setups faster than they expect. Write down the normal path for local, staging, and production, plus the standard way to handle secrets, migrations, rollbacks, and logs. In practice, one shared release path saves time and avoids avoidable mistakes.

Keep each rule concrete

Each rule should answer one direct question. When do we create a new service? Where does new data go? What is the default deployment route? Who approves an exception?

That last point matters. If someone wants a second database, a custom queue, or a special deployment flow, name the person or role who decides. In an early startup, that is often the CTO, founder, or fractional CTO.

Keep the page to one page, or close to it. If it turns into a handbook, people stop reading it and the old debates come back. Short defaults, plain language, and occasional updates work better than a long document nobody uses.

How to write the first version

Do not write this page from theory. Write it from the arguments your team has already had more than once in the last two months. If the same people keep spending 20 minutes debating whether a feature needs a new service, where data should live, or how something should ship, that debate belongs in the draft.

A simple way to collect material is to scan recent pull requests, planning notes, and chat threads. You are not looking for every technical choice. You are looking for the repeated ones that drain senior time.

Then sort those arguments into three groups: services, data, and deployment. That keeps the page short and makes it easier to use. Most principle documents fail because they try to cover everything.

A practical first pass looks like this:

• Write down the recurring arguments from the last two months.
• Group them under services, data, or deployment.
• Turn each group into one default rule.
• Add one short sentence explaining why the rule exists.
• Name who can approve an exception.

Each default rule should settle a common choice. Keep it plain. For services, you might write, "Keep new features in the main app unless scale, security, or team ownership requires a separate service." For data, "Keep one system as the source for customer records." For deployment, "Use one release path for every production change unless the team approves a special case."

The sentence about why the rule exists matters more than people expect. It gives context and makes the rule easier to accept. "Use one release path" lands better when the note below says it cuts setup work and makes rollbacks faster.

Before you publish the page, review it with the people who build and ship. Ask one blunt question: "Would this have ended the last argument faster?" If the answer is no, rewrite the rule until it would.

A simple example from a small team

Picture a five-person SaaS team with one product, one API, and a tight cloud budget. They move fast, but the same arguments keep returning. One engineer wants microservices because "we might need them later." Another wants one codebase until real traffic or team size forces a split. Nobody writes down a rule, so the team spends the same hour twice.

The data layer starts the same loop. The app already keeps users, billing, and product state in PostgreSQL. Then a new feature arrives, and someone asks for MongoDB because the payload looks less structured. Nobody can explain what problem SQL fails to solve, yet the team still debates it. If they add a second database, they also add more backups, more monitoring, and more failure points.

Releases create another drag. The product can ship through a basic pipeline, but one senior developer still runs a few manual commands before every production deploy. Those steps live in one person's head. When deadlines get tight, everyone waits for the same person.

In a situation like this, the main problem is not talent. The team lacks a small set of defaults.

A short rules page might say:

• Keep one codebase and one deployable app until load, security, or team ownership gives a clear reason to split.
• Use PostgreSQL by default for product data. Add another database only after the team writes down the limit SQL cannot handle.
• Ship every release through one shared pipeline. If a step matters, automate it.
• Pick tools that any engineer on the team can run, debug, and roll back.

Those four lines do not end debate forever. They improve it. Instead of arguing from taste, the team asks a simpler question: does this case break the rule? If the answer is no, they move on.

How to use the rules in daily work

A principles page pays off before coding starts. Bring it into planning and design reviews the same way you bring scope, deadlines, and risk. If a feature needs a new service, a new table, or a special deployment step, check the default rule first.

Start reviews with three simple questions: where should this live, where should its data go, and how should it ship? If the rule says "use the existing service unless load, security, or team ownership makes that a bad fit," treat that as the default. Teams move faster when the common path feels routine.

Use the page at a few fixed moments:

• during backlog grooming, when scope can still change
• in design review, before work gets approved
• at ticket kickoff, before code starts
• after release, if a real exception should become the new default

Exceptions need a written reason. Keep it short. Two or three sentences are usually enough. "We need a separate worker because this task can spike memory and slow user requests" is clear enough. Written reasons make reviews calmer because people discuss the tradeoff, not each other.

Store the page where the team already works. If engineers live in the issue tracker and product docs, put it there. If it sits in a separate wiki nobody opens, people will forget it exists.

Do not rewrite the rules after every opinion. Change them after the team makes a real decision, ships it, and sees the result. One loud argument should not move the defaults. Three similar exceptions in a month probably should.

Mistakes that make principles useless

The fastest way to kill architecture principles is to turn them into a policy manual. If the page runs for ten pages, nobody checks it during a busy week. People fall back to memory, habit, or whoever speaks first in the meeting.

The opposite mistake is making the rules so strict that people work around them. A principle should give a default, not trap the team. If every exception turns into a fight, engineers will hide the exception in the implementation and the document will lose authority.

Vague lines are just as bad. "Use the best tool" sounds smart, but it settles nothing. One person reads that as "pick the fastest option," another hears "pick the newest stack," and a third wants whatever they used at their last job.

A good rule usually has three parts:

• the default choice
• the reason for that choice
• who can approve an exception

Another common mistake is writing rules for rare edge cases. One painful migration or one odd client request can push a team to add a paragraph nobody will need again. Principles should cover the common path. Unusual cases belong in a runbook or ticket note, not on the main page.

Drift is the slowest failure, and it happens all the time. The document says one thing, but the codebase, deployment flow, and service choices say another. New hires then learn two systems at once: the written one and the real one.

The fix is simple. Review the page when the team changes how it works, after a major incident, or once a quarter. If the team keeps breaking a rule for good reasons, rewrite the rule. If the page does not match what people actually ship, the page is the problem.

Quick checks before you publish

A short page of principles should save time in real work, not just look tidy in a doc. If people still reopen the same arguments about service boundaries, data storage, or deployment after reading it, the draft needs more work.

Start with a simple test. Hand the page to a new hire and give them ten minutes. They should come away with the default path: when the team keeps code in one service, where new data goes, how releases happen, and who can approve an exception. If they need a long meeting to decode it, the writing is too vague.

Before you publish, check five things:

• Every rule should solve an argument the team already had.
• Each rule should show where exceptions make sense.
• The defaults should match the stack you run now.
• The rules should fit the budget you actually have.
• One person should own updates.

The easiest way to pressure-test the page is to replay a few recent decisions. Maybe the team argued about adding Redis, split one service into three too early, or added a staging step that slowed every release. Ask a plain question: would this page have settled that call in five minutes? If not, tighten the rule or remove it.

Specific wording helps. "Keep one Postgres database unless security or load forces separation" gives people a default and a clear reason to break it. "Choose the simplest option" sounds nice, but teams can bend it to mean anything.

Good principles often feel a bit boring. That is usually a good sign. Clear defaults, clear exceptions, and a clear owner will do more for a small team than a clever document nobody trusts.

What to do next

Do not write a handbook. Start with five to ten rules that cover the choices your team argues about most: when to add a service, how to store data, and how to ship changes. If a rule does not save time in real work, leave it out.

Keep each rule short enough that a busy engineer can read it in seconds. One sentence often works better than a long paragraph. "Default to one service until load or ownership forces a split" is clear. "Use PostgreSQL unless a plain reason points elsewhere" is clear too.

A simple first pass looks like this:

• Pick the repeat debates that show up in planning, reviews, and incident follow-up.
• Write 5 to 10 rules in plain language.
• Add one line under each rule that explains when an exception makes sense.
• Test the page for one month in real decisions.
• Rewrite any line that people read in different ways.

That one-month test matters. Teams often think a rule is clear until two senior engineers read it and reach opposite answers. When that happens, fix the wording fast. Good principles reduce discussion time. They should not create new arguments about what the rule "really means."

Then use the page every week. Pull it into sprint planning when a new feature pushes the system in a new direction. Use it in code review when someone wants a new database, queue, or service. Bring it up in postmortems if an outage came from a choice the team never made explicit. If the rules do not show up in daily work, people will forget them.

Some teams need an outside view to get this right. Oleg Sotnikov at oleg.is works with startups as a Fractional CTO and advisor, helping teams turn fuzzy preferences into practical rules for architecture, delivery, and AI-driven development. That kind of help is most useful when the rules stay short, tested, and tied to the tradeoffs your startup faces right now.