Skip to content

Address AI-induced inefficiencies #1

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
Codym48 wants to merge 8 commits into
base: main
Choose a base branch
from
Open

Address AI-induced inefficiencies #1

Changes from all commits
Commits
Show all changes
8 commits
Select commit Hold shift + click to select a range
3b2e7d7
Define efficient, mention sliding scale of return
Codym48 Jul 21, 2026
16a16a0
Provide why, context, and theory in MR descriptions
Codym48 Jul 21, 2026
c42b790
Do not burden others with AI slop
Codym48 Jul 21, 2026
b53ecfd
Rearrange MR sections for better flow
Codym48 Jul 21, 2026
c21ee12
Reinforce that the developer has to do the synthesizing
Codym48 Jul 21, 2026
403632b
Remove some less powerful bullets to mitigate growth
Codym48 Jul 21, 2026
ea9184e
Allow building, disallow promoting
Codym48 Jul 21, 2026
d20489c
Switch from gerund to verb to fix grammar
Codym48 Jul 21, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
14 changes: 8 additions & 6 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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
Expand All @@ -13,21 +15,21 @@ Rules to live by. Written using GitLab, git, and Jira terminology, but generaliz
- 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
- If a Jira ticket exists, reference it in MR description to automatically link and optionally close upon completion
- 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

@cameronbracco cameronbracco Jul 21, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I find myself wanting this to be stronger. I still like the idea of writing for a reviewer/future person looking at such that they can build their own mental model without looking at the code

For posterity, here was the original line I sent you (admittedly, tone doesn't match most of what is in this document):

MR descriptions should accurately capture your understanding of the problem space and the solution taken in enough detail such that a reviewer can build their own mental model of the changeset before ever looking at the code

@Codym48 Codym48 Jul 22, 2026

Copy link
Copy Markdown
Owner Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yeah, I was relying on the definitions embedded in those links that many people probably won't click. Could make the ask explicit first, and include the links as additional reading?

Suggested change
- 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
- Present your understanding of the problem space and your solution's position within it, so the reviewer can build a mental model before looking at code
- 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

- 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
- Unless that code is broken or terrible, in which case update it everywhere, not just in your new code
- 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)
Expand All @@ -43,7 +45,7 @@ Rules to live by. Written using GitLab, git, and Jira terminology, but generaliz
- 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 promote or rely on anything that you aren't willing and able to maintain
Comment on lines -46 to +48

@cameronbracco cameronbracco Jul 21, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Might be worth defining build vs promote here in a different line?

@Codym48 Codym48 Jul 22, 2026

Copy link
Copy Markdown
Owner Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Agree, but I'd like to find a way to do it very succintly.

  • "build" = create, which is incresingly worth doing, even with no intention to maintain it, if the use case is narrow and lifespan is tiny, since it's cheaper to do that via AI than ever before
  • "promote" = increase the use (and therefore blast radius), as newly defined at the top of the page: promote to the main branch of a heavily used repository, share widely among multiple teams or users that may implicitly expect you to maintain it, etc.

I could just say "promote to the trunk" as an approximation, but worry that's too narrow?

@cameronbracco cameronbracco Jul 22, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think "promote to the trunk" would be too narrow, but I like your definitions.

Maybe could be done in an active fashion? I don't know how you feel about the "but" in the second line essentially appending to the first vs being a totally separate line. If separate, I think it needs slightly more context to properly differentiate it from build/create

  • Make it easy to build and create software, even if the use case is narrow and the lifespan is tiny.
  • But do not promote or rely on anything you aren't willing and able to maintain
    • Existing bullets on maintaining software

- 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
Expand Down