Maintainable
Components have clearly defined and documented responsibilities and interfaces. The code is structured so that others can understand, maintain and change it.
A practical guide for development teams
AI Development
Team Practices
Explore the tradeoffs. Set your boundaries. Make an agreement your team can actually work with.
Define code quality
What is
good-quality code?
Start by agreeing what good-quality code means for your team. Two key ingredients are maintainability and code that clearly expresses its intent.
Expresses the intent
The code makes its intended behaviour clear and fulfils the agreed principles. Its purpose should be understandable, and its behaviour should match the requirements.
TEAM EXERCISE 5 minutes
What does good-quality code mean to your team?
Score how important each aspect is in your team's definition. Discuss different views and choose one score together.
Score what matters
These scores describe your priorities, rather than how your current code performs. Leave an aspect open if you still need to discuss it.
1 Context-dependent2 Useful3 Important4 Very important5 Essential
Maintainability
Clear intent
Read your suggested definition
0 of 6 aspects scored
Score the aspects that matter to your team to see a suggested definition of good-quality code.
Make the definition your own
Write your own definition, or use the suggestion and refine it together. Add examples and anything the scores missed. Your wording stays unchanged when you adjust the scores.
Choose the right role for AI
Clarity before
delegation.
Knowing what to build and knowing how to build it are different things. Explore what changes when either is unclear.
TECHNICAL CLARITY →
Product clarity increases from bottom to top
Select a quadrant to define the AI role, human responsibility and evidence for that situation. Each quadrant keeps its own answers.
DEFINE THIS SITUATION
Compare & prototype
Start with the prefilled example. Edit the three fields to capture what your team agrees.
Prefilled example
Adapted from the workshopThe campaign budget rules are clear. A backend developer asks AI to prototype an interface in an unfamiliar frontend stack. A frontend specialist reviews accessibility, state management and implementation choices.
A convincing prototype is not evidence that the implementation is ready for delivery. Resolve the technical uncertainty with qualified support.
This is a discussion framework from the workshop, not a permission system. Confidence alone is not clarity. If nobody can verify a delivery change, arrange support, narrow the scope or pause.
Manage the context
Treat your AI context
like your code.
How is your team working with AI today? Start with the practices you use, then shape a way to manage them together.
START WITH YOUR TEAM 3 questions
Which practices are part of your work?
Your answers shape the guidance below. Choose what describes your team today.
Skill files are reusable instructions and examples that help AI carry out a particular kind of task.
Agents use AI to work through tasks with tools, instructions and an agreed degree of independence.
Spec-driven development starts from a written description of intended behaviour and acceptance criteria that guides implementation and checks.
Answer a question to see guidance for your team.
Your team's next steps
Manage the work behind the work.
For the practices you adopt, make this the shared routine.
- Give it a home and an owner
Keep service context close to its code; keep reusable team and shared guidance in a named home with a maintainer.
- Version it in Git
Track instructions, specifications and examples together with their change history.
- Review and check changes
Use a pull request, a named reviewer and representative checks before accepting a change.
- Record the approved version
Pin tested shared versions and record the context used for a task so the team can trace its results.
- Maintain and retest
Set a review date; update and retest when behaviour, architecture, tools or team needs change.
Explore an example repository structure
Give each working asset a clear home. These names are examples; adapt the structure to your organisation.
Service repositoryservice-repo/specs/
Keep specs, acceptance criteria, plans and service-specific prompts close to the implementation.
Approve the spec before coding. Update it with the change.Team AI repositoryteam-ai/
Share reusable skills, prompts, examples and evaluation cases. Record usage notes and changes.
Name a maintainer. Publish tested, versioned releases.Shared engineering repositoryengineering-ai/
Maintain common rules, templates and skills used by several teams. Make owners and approved versions visible.
Pin a tested shared version. Link to sources from your docs.MAKE IT YOUR TEAM'S PRACTICE
Agree your guidelines
Create a starting draft from your answers, or write your own. Add real locations, owners and review moments. Changing your answers keeps your wording intact.
Make space for each other.
More generated code is not the same as a better team outcome.
Learn as a team
Talk about the work.
Then test the promise.
Give authors and reviewers room to compare experiences. Capture what you learned and what you want to follow up together.
These signals came from one colleague’s experience in the original workshop. They are conversation starters, not measured findings. Leave a choice open when you need to discuss it.
Consider a concrete use case in each area. Readiness belongs to the use case, not an entire discipline.
Explore gaps remain / Pilot scoped trial / Proven demonstrated / Scale ready for team use
TEAM REFLECTION 10 minutes
Capture your discussion
Summarise the shared insights, different experiences and open questions. Add any follow-up actions, who will take them forward and when to revisit them.
Define the scope
Same tool.
Different boundaries.
Permission depends on the service, task, data and environment. Make each boundary explicit.
DDevelopment
TTest
AAcceptance
PProduction
Permission in development does not carry into test, acceptance or production. A role ceiling never grants merge, deployment or data access by itself.
L / LimitedContained impact.
Straightforward recovery.
M / SignificantCustomer or business disruption.
Coordinated recovery.
H / CriticalSevere platform, financial
or sensitive-data impact.
BUILD YOUR BOUNDARY MAP
One service. One task. One environment.
Add a separate entry whenever the permissions change. Leave undecided fields open.
Make the agreement
Your team.
Your working agreement.
Turn the conversation into a draft you can review together, version and revisit.
Agree a maximum AI role
Choose for each situation within your stated scope. A higher ceiling is not a goal. Open means undecided; it is different from no AI.
What do the four roles mean?
- No AI
- No AI use for the agreed task, data and environment scope.
- Discovery
- Investigate, learn and compare options within approved access. Delivery implementation is outside this role.
- Assistance
- A human directs the work step by step. AI may draft changes or tests within that direction; the human chooses the approach and checks each step.
- Bounded delegation
- An agent executes a specified task with agreed tools, acceptance criteria and stop conditions. A human reviews and accepts or rejects the outcome.
Resolve technical objections; do not average the choices. Service boundaries and existing policies may restrict any role further.
What we owe each other
The pause rule
If no qualified person can verify a delivery change, arrange support, narrow its scope or pause implementation.
Take the conversation with you.
Your draft agreement
Draft for team discussion. Unresolved choices remain open.
Read your generated draft
Downloads as Markdown for your repository or docs. Exploring every chapter does not approve the agreement. Review it with the team before adopting it.