From 3b2e7d7d3968097d36da8fe91142262ab0def739 Mon Sep 17 00:00:00 2001 From: Cody Martin Date: Tue, 21 Jul 2026 10:35:36 -0700 Subject: [PATCH 1/8] Define efficient, mention sliding scale of return --- README.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/README.md b/README.md index 2a322fa..d0d462a 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,8 @@ # Efficient Development Rules to live by. Written using GitLab, git, and Jira terminology, but generalizable to any software development tools. +Efficient development minimizes total pain and suffering across the whole software lifecycle. As such, the return on these behaviors grows as the use of the software grows, in number of use cases, number of users, number of developers and maintainers, number of interfaces to external code and teams, and number of months or years that we expect the software to exist and be relevant. + - Use [trunk based development](https://trunkbaseddevelopment.com/) and avoid multiple persistent branches - Integrate early and often (continuously) - Give everyone (even people outside your team) developer access and don't attempt to control what they do From 16a16a04fddb08df4be62483a89a0f57949d967a Mon Sep 17 00:00:00 2001 From: Cody Martin Date: Tue, 21 Jul 2026 10:50:11 -0700 Subject: [PATCH 2/8] Provide why, context, and theory in MR descriptions --- README.md | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index d0d462a..459c676 100644 --- a/README.md +++ b/README.md @@ -15,9 +15,10 @@ Efficient development minimizes total pain and suffering across the whole softwa - MRs avoid the misinterpretation that often happens when playing telephone through email ➡ chat ➡ Jira ➡ git - Jira tickets are useful as a promise to do some work in the future that we don't have time to do now - Only if you actually promise to do that work - - Clear and comprehensive MR descriptions are far more important than individual commit messages - - Updating the MR description costs nothing, work on continuously improving it - - [GIFs](https://gifcap.dev/) in MR descriptions are incredibly powerful persistent demos +- Clear and comprehensive MR descriptions are far more important than individual commit messages + - Updating the MR description costs nothing, work on continuously improving it + - Focus on [why (and why not), not how](https://cbea.ms/git-commit/#why-not-how), providing context and [theory](https://pablo.rauzy.name/dev/naur1985programming.pdf) that isn't already visible in the diff + - [GIFs](https://gifcap.dev/) in MR descriptions are incredibly powerful persistent demos - If a Jira ticket exists, reference it in MR description to automatically link and optionally close upon completion - Make your work visible - Open draft MRs extremely early (even just a README update saying what you're going to go do) to allow early review and course correction From c42b790cc6ef2aab3275edf7cee161634f0eb602 Mon Sep 17 00:00:00 2001 From: Cody Martin Date: Tue, 21 Jul 2026 11:05:31 -0700 Subject: [PATCH 3/8] Do not burden others with AI slop MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit From https://lethain.com/make-no-assumptions/ > The author must be the first human in the loop for their output. The biggest cultural failure with harnesses is when you can tell that you–the recipient of a piece of work–are the first human in the loop reviewing it. You must set a cultural norm that the creator of a piece of content is always the first human in the loop before asking another human to review it. If you fail to set that cultural expectation, then you will quickly crush the remaining team with a high standard for quality reasoning, which will lead to a full destruction of your reasoning horizon. I switched from "reviewing" to "reading" since this could apply to all forms of written communication, like performance reviews. I added "and synthesized" to indicate that it's insufficient to simply review (look at) and validate (verify correctness, quality, appropriateness), the developer must go further and integrate the generated content into the larger context and their theories --- README.md | 1 + 1 file changed, 1 insertion(+) diff --git a/README.md b/README.md index 459c676..e8d84f0 100644 --- a/README.md +++ b/README.md @@ -23,6 +23,7 @@ Efficient development minimizes total pain and suffering across the whole softwa - Make your work visible - Open draft MRs extremely early (even just a README update saying what you're going to go do) to allow early review and course correction - Commit and push frequently +- Do not publish or burden others with reading something generated that you haven't validated and synthesized - Keep MRs small - Keep branches short-lived and merge from main frequently - Match existing code From b53ecfdf3960c9c7c3d455a75b87195152ec8e52 Mon Sep 17 00:00:00 2001 From: Cody Martin Date: Tue, 21 Jul 2026 11:06:57 -0700 Subject: [PATCH 4/8] Rearrange MR sections for better flow --- README.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index e8d84f0..aa48d92 100644 --- a/README.md +++ b/README.md @@ -15,14 +15,14 @@ Efficient development minimizes total pain and suffering across the whole softwa - MRs avoid the misinterpretation that often happens when playing telephone through email ➡ chat ➡ Jira ➡ git - Jira tickets are useful as a promise to do some work in the future that we don't have time to do now - Only if you actually promise to do that work +- If a Jira ticket exists, reference it in the MR description to automatically link and optionally close upon completion +- Make your work visible + - Open draft MRs extremely early (even just a README update saying what you're going to go do) to allow early review and course correction + - Commit and push frequently - Clear and comprehensive MR descriptions are far more important than individual commit messages - Updating the MR description costs nothing, work on continuously improving it - Focus on [why (and why not), not how](https://cbea.ms/git-commit/#why-not-how), providing context and [theory](https://pablo.rauzy.name/dev/naur1985programming.pdf) that isn't already visible in the diff - [GIFs](https://gifcap.dev/) in MR descriptions are incredibly powerful persistent demos -- If a Jira ticket exists, reference it in MR description to automatically link and optionally close upon completion -- Make your work visible - - Open draft MRs extremely early (even just a README update saying what you're going to go do) to allow early review and course correction - - Commit and push frequently - Do not publish or burden others with reading something generated that you haven't validated and synthesized - Keep MRs small - Keep branches short-lived and merge from main frequently From c21ee12a0527d97898379f9a118c7ac056d615ec Mon Sep 17 00:00:00 2001 From: Cody Martin Date: Tue, 21 Jul 2026 11:07:22 -0700 Subject: [PATCH 5/8] Reinforce that the developer has to do the synthesizing --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index aa48d92..f6b81cc 100644 --- a/README.md +++ b/README.md @@ -23,7 +23,7 @@ Efficient development minimizes total pain and suffering across the whole softwa - Updating the MR description costs nothing, work on continuously improving it - Focus on [why (and why not), not how](https://cbea.ms/git-commit/#why-not-how), providing context and [theory](https://pablo.rauzy.name/dev/naur1985programming.pdf) that isn't already visible in the diff - [GIFs](https://gifcap.dev/) in MR descriptions are incredibly powerful persistent demos -- Do not publish or burden others with reading something generated that you haven't validated and synthesized +- Do not publish or burden others with reading something generated that you haven't validated and synthesized yourself - Keep MRs small - Keep branches short-lived and merge from main frequently - Match existing code From 403632b55556797c552a6cf3d9da859253d17b84 Mon Sep 17 00:00:00 2001 From: Cody Martin Date: Tue, 21 Jul 2026 11:10:37 -0700 Subject: [PATCH 6/8] Remove some less powerful bullets to mitigate growth --- README.md | 2 -- 1 file changed, 2 deletions(-) diff --git a/README.md b/README.md index f6b81cc..2f0ded9 100644 --- a/README.md +++ b/README.md @@ -22,7 +22,6 @@ Efficient development minimizes total pain and suffering across the whole softwa - Clear and comprehensive MR descriptions are far more important than individual commit messages - Updating the MR description costs nothing, work on continuously improving it - Focus on [why (and why not), not how](https://cbea.ms/git-commit/#why-not-how), providing context and [theory](https://pablo.rauzy.name/dev/naur1985programming.pdf) that isn't already visible in the diff - - [GIFs](https://gifcap.dev/) in MR descriptions are incredibly powerful persistent demos - Do not publish or burden others with reading something generated that you haven't validated and synthesized yourself - Keep MRs small - Keep branches short-lived and merge from main frequently @@ -31,7 +30,6 @@ Efficient development minimizes total pain and suffering across the whole softwa - Drive MRs to closure before opening new ones - Unless you find a bug that can be spun off and completed via a smaller incremental MR sooner - Make time to review teammates' MRs on a recurring basis - - Like while waiting on review of your MR and after you finish it before you start the next one - Resolve MR concerns efficiently - Developers are empowered to resolve threads about typos when they make the fix - Larger / open-ended / architectural concerns shall be resolved by the originator of the thread (only) From ea9184eccdea6e5550183303cd43ce970bd346e3 Mon Sep 17 00:00:00 2001 From: Cody Martin Date: Tue, 21 Jul 2026 11:15:33 -0700 Subject: [PATCH 7/8] Allow building, disallow promoting "don't build" has always felt a bit prescriptive and constraining. I've found myself both (1) _not_ writing a script for fear of having to maintain it later, even though I probably should've written the throw-away tool instead of doing the thing manually, and (2) chafing at it and deciding "heck with it, I'm going to build the fragile thing anyway." The massive adoption of AI and Claude Code shifts the landscape, making it much cheaper to build throw-away scripts for specific uses. We shouldn't discourage this, for many reasons, but should avoid _promoting_ unmaintainable things to the trunk or main branch. --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 2f0ded9..31100e8 100644 --- a/README.md +++ b/README.md @@ -45,7 +45,7 @@ Efficient development minimizes total pain and suffering across the whole softwa - Establish coding standards early and automate enforcement - Don't spend any time arguing about coding standards that aren't automatically enforced - Checklists are useful, only for things that can't be automated -- Don't build or rely on anything that you aren't willing and able to maintain +- Don't promoting or rely on anything that you aren't willing and able to maintain - You aren't able to maintain plain text documentation of source code ... autogenerate it instead - You aren't able to maintain complex shell scripts - You aren't able to maintain anything that doesn't have tests From d20489c8d52b40734ef50aa2b7407d0143f662e9 Mon Sep 17 00:00:00 2001 From: Cody Martin Date: Tue, 21 Jul 2026 11:20:52 -0700 Subject: [PATCH 8/8] Switch from gerund to verb to fix grammar --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 31100e8..e786c52 100644 --- a/README.md +++ b/README.md @@ -45,7 +45,7 @@ Efficient development minimizes total pain and suffering across the whole softwa - Establish coding standards early and automate enforcement - Don't spend any time arguing about coding standards that aren't automatically enforced - Checklists are useful, only for things that can't be automated -- Don't promoting or rely on anything that you aren't willing and able to maintain +- Don't promote or rely on anything that you aren't willing and able to maintain - You aren't able to maintain plain text documentation of source code ... autogenerate it instead - You aren't able to maintain complex shell scripts - You aren't able to maintain anything that doesn't have tests