[{"data":1,"prerenderedAt":115},["ShallowReactive",2],{"blog:zh:how-we-agree-on-a-shape":3},{"id":4,"title":5,"author":6,"body":7,"date":101,"description":102,"extension":103,"meta":104,"navigation":105,"path":106,"publishAt":101,"seo":107,"stem":108,"tags":109,"__hash__":114},"blog_en\u002Fblog\u002Fhow-we-agree-on-a-shape\u002Fen.md","How We Agree on a Shape Before We Build It","Aptli",{"type":8,"value":9,"toc":91},"minimark",[10,15,19,22,26,29,32,36,39,42,45,49,52,55,59,62,65,69],[11,12,14],"h2",{"id":13},"where-we-left-off","Where We Left Off",[16,17,18],"p",{},"A few weeks ago we wrote about how our front end gets the same design patterns a Java developer would recognize out of tables and composables, with almost no classes anywhere. The conversation about it did not end when we hit publish. Inside the team it kept going, because the piece touched something bigger than any one pattern: we had a name for each of these shapes, and everyone already knew what the name meant before the conversation started.",[16,20,21],{},"That habit deserves its own explanation, separate from any specific pattern. Someone decided, a while back, that naming a shape and writing it down was worth the time, and the team has kept doing it since.",[11,23,25],{"id":24},"what-a-tutorial-teaches","What a Tutorial Teaches",[16,27,28],{},"Component libraries are a real convenience. Pull one in, and a working date picker or dropdown arrives already built, tested by a lot more use than any one team could give it on its own. A code snippet saves the ten minutes it takes to recall the exact syntax for something done rarely enough to forget. A tutorial is often the fastest way to actually learn a technique, because it walks through the reasoning behind it.",[16,30,31],{},"All of that is useful, and it is aimed at one person, learning one technique, in one sitting. A team has a second question: what a group of people, most of whom did not write the original code, should reach for the next time the same kind of decision comes up. That answer belongs to the team.",[11,33,35],{"id":34},"the-actual-practice","The Actual Practice",[16,37,38],{},"Here is roughly how it happens for us. Someone notices the same shape of problem showing up a second or third time, usually while reviewing a pull request that solves it a little differently than the last one did. They give the shape a name in the conversation, in the review comment itself. If the name survives being used a few more times, it gets written down: what the shape is, when it applies, and a short example already sitting in the codebase.",[16,40,41],{},"The written list stays short on purpose and covers the shapes the team uses. It exists so a design decision can be a sentence. When someone writes \"make that a registry\" in a review, everyone reading the comment already knows the shape being asked for, with no diagram and no meeting.",[16,43,44],{},"The other place it earns its keep is a new engineer's first week. Reading the list, they learn the handful of shapes the codebase uses, in the team's own words. A style guide covers how to format a line. This list covers how to think about a decision before the line is written.",[11,46,48],{"id":47},"why-we-bother","Why We Bother",[16,50,51],{},"Naming a shape takes a conversation, and writing it down takes someone's time, revisited as the codebase changes. The payoff is the one the book we mentioned last time argues for directly: a shared name makes a good decision fast, and it makes a poor one visible while it is still a sentence, before it turns into a pull request that has to be unwound.",[16,53,54],{},"The notification engine we described last time, still about forty lines after every addition, held up for exactly this reason. The shape had a name before the fourth or fifth notification arrived. Adding one after that took no deliberation.",[11,56,58],{"id":57},"the-human-part-of-an-architectural-decision","The Human Part of an Architectural Decision",[16,60,61],{},"This is a habit of how a group of people agree on things, before it is a coding practice. A team decides, one review and one conversation at a time, and the list keeps those decisions once they are made. Each decision gets made once.",[16,63,64],{},"That holds whether the language is Java or JavaScript, and whether the team is five people or fifty. The shape in the code follows from the shape of how the people building it talk to each other about it, and that second part is the one we spend the most deliberate attention on.",[11,66,68],{"id":67},"summary","Summary",[70,71,72,76,79,82,85,88],"ul",{},[73,74,75],"li",{},"Component libraries, snippets and tutorials each teach a technique to one person in one sitting. A shared vocabulary for a design shape lives between people on a team, and gets used by everyone at once.",[73,77,78],{},"The practice, concretely: a name proposed in a review comment, tested against a few more real cases, then written down with what it is, when it applies, and a short example already in the codebase.",[73,80,81],{},"The written list stays short on purpose. It exists so a design decision can be a sentence.",[73,83,84],{},"A new engineer reads the list in their first week. They learn the shapes the codebase actually uses, in the team's own words, without piecing them together from old code.",[73,86,87],{},"The payoff is the same one the book behind our last piece argues for: a shared name makes a good decision fast, and a poor one visible while it is still a sentence.",[73,89,90],{},"This is an organizational habit before it is a coding one. A team agrees on things, one conversation at a time, and the list is where those agreements get kept.",{"title":92,"searchDepth":93,"depth":93,"links":94},"",2,[95,96,97,98,99,100],{"id":13,"depth":93,"text":14},{"id":24,"depth":93,"text":25},{"id":34,"depth":93,"text":35},{"id":47,"depth":93,"text":48},{"id":57,"depth":93,"text":58},{"id":67,"depth":93,"text":68},"2026-09-16","A few weeks ago we wrote about how design patterns show up in our code without classes. The conversation inside our own team did not stop when we hit publish. This is the habit underneath all of it, and why we treat it as deliberate work.","md",{},true,"\u002Fblog\u002Fhow-we-agree-on-a-shape\u002Fen",{"title":5,"description":102},"blog\u002Fhow-we-agree-on-a-shape\u002Fen",[110,111,112,113],"engineering","how-we-work","design-patterns","team-alignment","DmAcL-2SDauEZH4B-VAe6yo4UuG68NF81SsXgK5ZkyQ",1791936502680]