Toward the beginning of a project, an architect, TL or developer often has to plan out exactly how a feature will be executed, and there is rarely only one way to do it. In fact there's often many ways, and often multiple different platform providers trying to get you on a demo call to show why theirs is the best.
Software architects deal in trade-offs, and in order to make good decisions, a sensible process and framework should be established. What are the architectural principles for this project? What are the business constraints? Does the sponsor want it to look like a capex investment, or an ongoing cost?
The goal of approaches is to help architects as they work through prospecting different solutions. It gives them a place to describe each solution being investigated, and record progress against them. It also gives the architect a place to easily see what decisions are outstanding and therefore what they need to focus on next. In fact we thought this part was so important it got its own "Decisions workspace" at the top of the nav.
What are the features and why did we think they are important?
-
Approach status can be set to proposed, In PoC, shortlisted, planning, adopted, live, retiring, sunset or rejected. The statuses reflect real world scenarios for approaches that are still being discovered, have been put live, or have been live before and retired. They are also honest about where the evidence comes from, so you can tell at a glance whether someone has actually built a spike or is arguing from a vendor's landing page.
-
Why it works and why it doesn't are separate fields, deliberately. It is easy to write up an option in its best light, and an option written up only in its best light is a pitch rather than something a team can weigh. Making the drawbacks a field of their own means somebody has to fill it in.
-
A side-by-side comparison of the candidates linked to a decision, so the options can be read across rather than hunted for in three different documents. You can rank them, star the front-runner, and mark the decision made, which sets the winner to adopted and the rest to rejected in one go.
-
Rejected approaches keep their reasoning. They are not deleted. Six months later, when somebody asks why you didn't just use the obvious thing, the answer is on the page rather than in the memory of whoever ran the spike.
-
Platform compatibility tags record what an approach is actually proven against: works with, requires, or is incompatible with a named platform at a given version. A solution is a claim about a platform, and platforms move on their own schedule.
-
Versions, because those platforms move. Each approach is a version family, so when a vendor's next API release changes the picture you cut a new version and the old one stays as read-only history.
-
Promotion to an organisation-level library, so a solution that has proven itself on one project becomes the starting point for the next one.
-
Readable by AI agents over MCP, so the agent implementing the feature can see which approach you adopted, and which ones you ruled out, before it writes any code.
Recording the candidates
Each option you are prospecting goes down as its own approach. The form is deliberately plain: a title, a summary, the status, a description, and then the two fields that carry the weight, why it works and why it doesn't.
Filling in the second of those is the part people skip, and it is the part that makes the rest of this useful. The trade-off you did not write down is the one that gets rediscovered by the next team, usually at the worst possible moment.
Once a few candidates are in, the list gives you the shape of the problem at a glance: what is still just an idea, what has a proof of concept behind it, and what has already been ruled out.
Comparing them, and deciding
When the candidates belong to a decision, the workspace lines them up side by side. Summary, why it works, why it doesn't, and status, read across rather than down.
This is usually the artefact the client or the sponsor wants anyway. They are rarely interested in the winner on its own; they want to know what else was considered and why it lost, particularly when the option they had heard of is the one you are not recommending.
Marking the decision made sets the front-runner to adopted and the rest to rejected, and the rejected ones keep everything that was written about them.
Keeping a solution honest as the platform moves
A solution is a claim about a platform, and platforms do not hold still. Shopify versions its APIs on a calendar. An approach that worked cleanly against the Storefront API last year may rely on a field that a later version quietly dropped.
So each approach carries platform compatibility tags, and each one is a version family.
The tags are simple, and that is the point:
An entry that just says "this works" is not much use to the next person. An entry that says what it works against, and at which versions, is something they can actually reach for. When a platform release changes the picture, you create a new version with updated compatibility, and the previous one stays as read-only history, so the family reads as a record of how the solution held up and where it had to change.
Proven solutions bubble up
This is the part that changes what happens on the next project.
A lot of the capabilities you are asked to deliver are not unique to the client asking for them. Subscriptions on a platform that was not really designed for them. Returns and exchanges that the client's ops team can actually run. Keeping a product catalogue in sync between an ERP and the storefront. Click and collect. B2B pricing and quotes. These come up client after client, and the usual pattern is that each project works the answer out from scratch, or picks differently because the person who learned the lesson last time is on another account now.
So an approach that has proven itself can be promoted out of the project into an organisation-level library that every project can draw on. Promoting copies it up and links the original back to it, so the provenance survives in both directions. You can see where a solution was proven, and everywhere it has been used since.
That is the common solutions library: not a wiki page of good intentions, but the set of solutions your organisation has actually shipped, with the trade-offs that were weighed to get there and the platform versions they are valid against. The first project to work out subscriptions on Shopify pays full price for it. The projects after it start from proven ground, and spend their time on whatever is genuinely different about the client in front of them.
The agents read this too
An AI coding agent implementing a feature makes the same call your engineers make about how to solve something, and by default it makes that call from general knowledge rather than from anything your team has proven.
Because approaches are structured records rather than prose, an agent connected over MCP can read them before it writes anything. It can call list_approaches to see the candidates in a project and where each one stands, and get_approach to read one in full, including why it works and where it does not. So the agent builds on the option your team actually chose, and it can see the ones you ruled out and why, instead of confidently reinventing the approach you rejected last year.
Where this leaves you
Prospecting solutions has always been a big part of the job, and it has usually been the part that leaves the least behind. Approaches give you somewhere to put it: the candidates, the trade-offs you weighed against the business and against your principles, and the decision you reached. The ones that prove themselves rise out of the project and into a library the whole organisation can build on.
One honest note to finish on. Architectural principles are not yet a first-class record in Specsource, so today they live in the reasoning you attach to each approach and decision. Making them explicit, so a principle can be stated once and referenced by everything it shapes, is where we want to take this next.