From 5d8483f621ccc5c74f50fbefeffb959dbff6181d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jesper=20S=C3=B8rensen?= Date: Tue, 16 Jun 2026 16:11:45 +0200 Subject: [PATCH 1/7] Commit messages: Add section about agents --- technical_practices/commit_messages.md | 13 +++++++++++++ 1 file changed, 13 insertions(+) diff --git a/technical_practices/commit_messages.md b/technical_practices/commit_messages.md index 694f519..702c501 100644 --- a/technical_practices/commit_messages.md +++ b/technical_practices/commit_messages.md @@ -15,3 +15,16 @@ https://www.freecodecamp.org/news/how-to-write-better-git-commit-messages/ > * What effect have my changes made? > * Why was the change needed? > * What are the changes in reference to? + +## Agent-generated commit messages + +As long as the commit messages are good (according to the above advice), it is not important how they are made. + +However, we do often see that agent-generated messages are: + +- Just a compressed version of the code changes +- Not good at communicating the intention (the *why*). +- Too verbose (they are often overly long and include unimportant technical details) + +To avoid this, devs are advised to write commit messages themselves, or at least put in some degree of effort to communicate intention. +This also works as a nudge towards understanding the code that will be committed. From d7cfcb5721974b7c41049921e8e75711532c8e1d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jesper=20S=C3=B8rensen?= Date: Thu, 2 Jul 2026 08:06:25 +0200 Subject: [PATCH 2/7] WIP: Agentic programming --- technical_practices/agentic_programming.md | 156 +++++++++++++++++++++ 1 file changed, 156 insertions(+) create mode 100644 technical_practices/agentic_programming.md diff --git a/technical_practices/agentic_programming.md b/technical_practices/agentic_programming.md new file mode 100644 index 0000000..09e9219 --- /dev/null +++ b/technical_practices/agentic_programming.md @@ -0,0 +1,156 @@ +# PLAIbook — Abtion's AI-first work guidelines + +This guide outlines good agentic development practices at Abtion. + +Most of the information in here is merely recommendations. Devs free to deviate from these guidelines as they see fit. However! The output (commits, code, tests, etc.) should follow our best practices. + +## Where we are, where we are headed + +AI tools are improving rapidly, and so will this document. +This document describes the now, and thus won't focus a lot on - for instance - autonomouse agents (We simply haven't established best practices yet) + +### Where we are now + +- The developer is the architect (assisted by an agent with project context) +- All work is primarily implemented locally by developers, mostly with agentic programming + +There are experiments with: +- AI agents autonomously generating pull requests based on project tasks. +- Standardizing task descriptions to make them more agent friendly (for both controlled and autonomous agents) +- Generating - the initial version of - minor projects based on designs from claude design. + +### Where we - currently believe that we - are headed + +- The developer is still the architect +- Initial boiler plate is generated from a design, based on a template +- Non-complex work is mostly done by autonomous AI agents (PRs reviewed/refactored if needed by human developers) +- Complex work is implemented locally by developers (still using agentic programming) + +## Project setup checklist + +Agents work best when the right context is available for them to load when needed. + +Use the following checklist to set up context for your project: + +- [ ] `AGENTS.md` and symlink it from `CLAUDE.md` +- [ ] `docs/architecture.md`. Explains overall architecture of the project, reference in `AGENTS.md` +- [ ] `docs/decisions/*.md`. Information about important architectural decisions, referenced in `AGENTS.md` +- [ ] `.agents/skills/*`. Skills scoped to the project (for generally useful skills see: [how to create and share skills across projects](#how-to-create-and-share-skills-across-projects)) +- [ ] `.agents/.mcp.json`. MCP server configuration, scoped to development of the specific project +- [ ] `.agents/skills/agent-setup/SKILL.md`. Sets up MCP servers and skills for the used agent (ask agent to `invoke ".agents/skills/agent-setup/SKILL.md"`) + +Some of these files will be pre-populated by our templates, make sure to adjust them for the project. + +> [!TIP] +> If a project is large or complex, split the contents of `docs/architecture.md` file into separate sections. Then reference each section in an overarching `docs/architecture.md`. This will make it easier for the agent to find the right information without scanning the entire repository. + +### A note on monorepos + +In monorepo projects, do the project setup checklist per-project, then add `AGENTS.md` (and `CLAUDE.md`) to the project root. It should explain the monorepo structure and list all the projects. + +## Prerequisites for agentic programming + +- At least one coding agent installed, for instance: + - Claude code + - Codex + - OpenCode +- A text editor for manual changes. + +> [!TIP] +> There are many tools and editors available that facilitate agentic programming, either by providing their own agent harness, or by wrapping one or more coding agents. Tested and popular tools are: +> - Conductor +> - Cursor +> - VSCode + Claude extension +> - VSCode + Copilet +> - Zed + +## A basic agentic programming workflow + +Below is a good starting point for building with agentic programming, based on experiences from Abtion devs. +This is intentionally not an all-encompassing guide it's meant as a foundation to built on, and devs are expected to reshape the workflow to match how they prefer to work. + +### 1. Have the project installed on your local machine + +Follow the project instructions + +### 2. Grab a task in the project management tool + +Before working on a task, make sure that it feels workable. + +An agent might help you understand what to do, but don't work on the task until you feel confident about what needs to be done. + +### 3. Plan the development of the task with the AI agent + +Feed the task to your agent, and let it plan the development of the task. + +It is important that you refine the plan based on your own understanding of the task and the project. Make the agent to ask you about any unclear aspects or decisions to be made (you can use a skill like [grill-me](https://www.skills.sh/mattpocock/skills/grill-me) for this) + +This step is where the bulk of the focus should be spent, don't rush through it. + +> [!TIP] +> Use a good model for this step + +> [!TIP] +> If the plan is long, break it into smaller steps that can be committed separately. This eases the burden of reviewing generated code. + +### 4. Implement the task + +When you feel confident about the plan, tell the agent to implement it (one step at a time). + +> [!TIP] +> If the change isn't too complex, you can use a fast model for this. + +After executing the plan (or step), manually test the change (if possible) to ensure it works as expected. + +Depending on the complexity and importance of the change, review the code accordingly. + +**IMPORTANT**: Changes to important business logic must be reviewed thoroughly. Stylistic changes can be reviewed more superficially. + +> [!TIP] +> It can be a good idea to have another model review the code first, to filter out noise. + +> [!TIP] +> Agents have a tendency to expand on code, even when it's not needed. Be on the lookout for unnecessary changes or one line utils. + +### 5. Commit the change + +When you are satisfied with the change, make a commit. Be sure to follow the [commit message guidelines](commit_messages.md). +Then, when you are ready; create a PR (ask for a review if necessary), wait for CI to pass, then merge it - like you would have done without AI assistance. + +> [!IMPORTANT] +> Don't ask other devs to thoroughly review code that you have only superficially read yourself. If you are not entirely confident about the code (perhaps touching a part of the codebase you are not yet intimately familiar with), jump in a meeting rather than passing on something you don't fully understand. + +## Working on multiple tasks in parallel + +Since it takes time for agents to implement plans, it can feel inefficient to sit and wait for the agent to finish. + +The obvious solution is to work on multiple tasks in parallel, and many tools are built around or directly support this ([Conductor](https://www.conductor.build/), [Cursor](https://cursor.com/), [herdr](https://herdr.dev/), [Zed](https://zed.dev/), [VS Code](https://code.visualstudio.com/)) + +It is recommended to have a separate [worktree](https://git-scm.com/docs/git-worktree) for each task to avoid conflicts. This is often something the tool will let you do out of the box. + +It is our recommendation to be thoughtful about working on things in parallel. Based on an internal survey (June 2026), while devs tend to answer that parallel work makes them more productive, the conclusion is not very clear. Also no devs found it ideal to work on more than at most 3 tasks at a time. + +> [!TIP] +> Try if you can spent the "idle" time on thinking about or researching the task at hand (or working on something that supports the task). + +## Guidelines for AI-generated PRs + +On some projects we are experimenting with autonomous agents, letting them create and submit PRs on their own. + +While this might save us some time, it also introduces security / economic concerns. Agents can easily get stuck in loops, and they are vulnerable to prompt injections. + +For those reasons, it is a requirement that autonomous agents: + +- Do not have access to confidential keys and or tokens +- Are not able to commit to the main branch +- Can only submit draft PRs +- Have a hard TTL (e.g. they are killed if they take too long) + +## Guidelines for AI in client work (transparency, quality bar, what we tell clients) + + +## Prompt engineering basics and Abtion-specific patterns + +Is this still needed? + +## How to create and share skills across projects From d9c423c85c37e0058d708ad72284eeeb2c440cdb Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jesper=20S=C3=B8rensen?= Date: Wed, 8 Jul 2026 14:15:48 +0200 Subject: [PATCH 3/7] Update technical_practices/agentic_programming.md Co-authored-by: Rune Philosof <57357936+runephilosof-abtion@users.noreply.github.com> --- technical_practices/agentic_programming.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/technical_practices/agentic_programming.md b/technical_practices/agentic_programming.md index 09e9219..77d3546 100644 --- a/technical_practices/agentic_programming.md +++ b/technical_practices/agentic_programming.md @@ -131,7 +131,7 @@ It is recommended to have a separate [worktree](https://git-scm.com/docs/git-wor It is our recommendation to be thoughtful about working on things in parallel. Based on an internal survey (June 2026), while devs tend to answer that parallel work makes them more productive, the conclusion is not very clear. Also no devs found it ideal to work on more than at most 3 tasks at a time. > [!TIP] -> Try if you can spent the "idle" time on thinking about or researching the task at hand (or working on something that supports the task). +> Try if you can spend the "idle" time on thinking about or researching the task at hand (or working on something that supports the task). ## Guidelines for AI-generated PRs From 2333df203819ab83e8f8cdc1474d822d228f80e6 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jesper=20S=C3=B8rensen?= Date: Wed, 8 Jul 2026 14:16:02 +0200 Subject: [PATCH 4/7] Update technical_practices/agentic_programming.md Co-authored-by: Hari Abtion --- technical_practices/agentic_programming.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/technical_practices/agentic_programming.md b/technical_practices/agentic_programming.md index 77d3546..986eb98 100644 --- a/technical_practices/agentic_programming.md +++ b/technical_practices/agentic_programming.md @@ -16,7 +16,7 @@ This document describes the now, and thus won't focus a lot on - for instance - There are experiments with: - AI agents autonomously generating pull requests based on project tasks. -- Standardizing task descriptions to make them more agent friendly (for both controlled and autonomous agents) +- Standardizing many parts of the flow to make them more agent-friendly. Right now that includes task descriptions, autofixing agents, and gathering, summarizing, and processing large contexts from multiple sources, including meetings. - Generating - the initial version of - minor projects based on designs from claude design. ### Where we - currently believe that we - are headed From 4dc98b9ee8d368ca716bca19be63a3d8dd8b1f3b Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jesper=20S=C3=B8rensen?= Date: Wed, 8 Jul 2026 14:16:12 +0200 Subject: [PATCH 5/7] Update technical_practices/agentic_programming.md Co-authored-by: Hari Abtion --- technical_practices/agentic_programming.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/technical_practices/agentic_programming.md b/technical_practices/agentic_programming.md index 986eb98..af9be80 100644 --- a/technical_practices/agentic_programming.md +++ b/technical_practices/agentic_programming.md @@ -11,7 +11,7 @@ This document describes the now, and thus won't focus a lot on - for instance - ### Where we are now -- The developer is the architect (assisted by an agent with project context) +- The developer is the architect with the vision, judgment, and responsibility. The agents execute the work with the relevant context. - All work is primarily implemented locally by developers, mostly with agentic programming There are experiments with: From b02710408cbe084b3380f1323f42cae5a5b6d8fc Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jesper=20S=C3=B8rensen?= Date: Wed, 8 Jul 2026 15:41:17 +0200 Subject: [PATCH 6/7] Apply suggestion from @hcarreras Co-authored-by: Hari Abtion --- technical_practices/agentic_programming.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/technical_practices/agentic_programming.md b/technical_practices/agentic_programming.md index af9be80..6922609 100644 --- a/technical_practices/agentic_programming.md +++ b/technical_practices/agentic_programming.md @@ -7,7 +7,7 @@ Most of the information in here is merely recommendations. Devs free to deviate ## Where we are, where we are headed AI tools are improving rapidly, and so will this document. -This document describes the now, and thus won't focus a lot on - for instance - autonomouse agents (We simply haven't established best practices yet) +This document describes the now, and thus won't focus a lot on - for instance - autonomous agents (We simply haven't established best practices yet) ### Where we are now From 902639cd9f096c892f0f5823638b803685a5e268 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jesper=20S=C3=B8rensen?= Date: Wed, 8 Jul 2026 15:56:22 +0200 Subject: [PATCH 7/7] WIP: Agentic programming --- technical_practices/agentic_programming.md | 15 ++++++++------- 1 file changed, 8 insertions(+), 7 deletions(-) diff --git a/technical_practices/agentic_programming.md b/technical_practices/agentic_programming.md index 6922609..0f09690 100644 --- a/technical_practices/agentic_programming.md +++ b/technical_practices/agentic_programming.md @@ -83,7 +83,7 @@ An agent might help you understand what to do, but don't work on the task until Feed the task to your agent, and let it plan the development of the task. -It is important that you refine the plan based on your own understanding of the task and the project. Make the agent to ask you about any unclear aspects or decisions to be made (you can use a skill like [grill-me](https://www.skills.sh/mattpocock/skills/grill-me) for this) +It is important that you refine the plan based on your own understanding of the task and the project. Make the agent ask you about any unclear aspects or decisions to be made (you can use a skill like [grill-me](https://www.skills.sh/mattpocock/skills/grill-me) for this). This step is where the bulk of the focus should be spent, don't rush through it. @@ -91,7 +91,7 @@ This step is where the bulk of the focus should be spent, don't rush through it. > Use a good model for this step > [!TIP] -> If the plan is long, break it into smaller steps that can be committed separately. This eases the burden of reviewing generated code. +> If the plan is long, break it into smaller steps (vertical slices when possible) that can be committed separately. This eases reviewing burden. ### 4. Implement the task @@ -104,13 +104,14 @@ After executing the plan (or step), manually test the change (if possible) to en Depending on the complexity and importance of the change, review the code accordingly. -**IMPORTANT**: Changes to important business logic must be reviewed thoroughly. Stylistic changes can be reviewed more superficially. +> [!IMPORTANT] +> Changes to business logic must be reviewed thoroughly. Cosmetic changes can be reviewed more superficially. > [!TIP] -> It can be a good idea to have another model review the code first, to filter out noise. +> To futher ease the review burden it can be a good idea to have another model review the code first. > [!TIP] -> Agents have a tendency to expand on code, even when it's not needed. Be on the lookout for unnecessary changes or one line utils. +> Agents can unnecessarily expand on code or add unwanted side effects. Limit the changes to the scope of the task and be on the lookout for side journeys into new unnecessary "bugfixes", utility functions, and services. ### 5. Commit the change @@ -128,10 +129,10 @@ The obvious solution is to work on multiple tasks in parallel, and many tools ar It is recommended to have a separate [worktree](https://git-scm.com/docs/git-worktree) for each task to avoid conflicts. This is often something the tool will let you do out of the box. -It is our recommendation to be thoughtful about working on things in parallel. Based on an internal survey (June 2026), while devs tend to answer that parallel work makes them more productive, the conclusion is not very clear. Also no devs found it ideal to work on more than at most 3 tasks at a time. +Though spinning up many agents might seem like an obvious way to boost productivity, be thoughtful about working on things in parallel. Based on an internal survey (June 2026), while devs tend believe that parallel work make them more productive, the conclusion is not clear. Also all devs found it ideal to work on 1-3 tasks at a time. > [!TIP] -> Try if you can spend the "idle" time on thinking about or researching the task at hand (or working on something that supports the task). +> Instead of grabbing another task while the agent churns, try reflecting on the task at hand. There might other ways to advance the task than what the agent is currently doing. ## Guidelines for AI-generated PRs