The Interplay Between Soft As Code Disciplines · Architecture as Code: the course

All courses / Architecture as Code / Module 5 / Chapter 23

Learning objectives

After the lesson the participant can:

Describe the shared DNA that unifies the soft as-code disciplines.
Explain the distinct roles of Compliance, Architecture and Documentation as Code and how each strengthens the others.
Draft a team norms file and a lessons-learned entry as version-controlled artefacts.
Identify the challenges of combining the disciplines and plan an incremental adoption.

Key concepts

Shared DNA: The three properties into which soft artefacts are converted: structured representation in machine-readable formats, version control with history and pull requests, and automatability, so that artefacts can feed tools that generate reports, verify compliance or trigger workflows.
Compliance as Code as quality engine: Codified controls that reinforce the other disciplines through rule reuse, continuous validation and transparency. When a rule changes, the update propagates to every system that uses it.
Architecture as Code as hub: The connection between technical implementations and the policy and documentation layers, giving traceability to compliance rules, real-time documentation generated from models, and automated quality gates before an architectural change is approved.
Culture as Code: Team agreements and working norms moved out of slide decks and corridor conversations into version-controlled files, such as a team norms file, where a pull request records who proposed a change, the discussion and when the new norm took effect.
Knowledge as Code: Lessons learned and patterns kept in structured, queryable registries instead of wikis that drift. Pipelines validate required fields and check that referenced decision records exist, and search surfaces relevant lessons.

Interactive exercises

Do them here and get feedback at once. Choose a card and then where it belongs, or drag it.

Interactive exercise 1 · Match

Challenges of the interplay

Match each challenge of combining the soft as-code disciplines to the way the chapter describes it.

Interactive exercise 2 · Scenario

All disciplines at once

Read the situation and choose what the chapter's reasoning leads to. Each choice gives feedback.

Teaching plan

15 min	Teacher presents the shared DNA and the three roles: quality engine, hub and communication layer.
15 min	Walk through the two scenarios, a policy change and a new product launch, tracing what each discipline does and in which order.
10 min	Teacher explains Culture as Code and Knowledge as Code with the two worked files, then the four challenges and five adoption strategies.
30 min	Exercise in teams: write a team norms file and a lessons-learned entry, and review another team's through a simulated pull request.
5 min	Close on the future perspective: the more of the soft fabric is codified, the greater the demands on access control, privacy and accountability.

Discussion

The chapter describes pull requests on policy code as educational moments where lawyers, security experts and developers meet. What would each need in order to take part on equal terms?
Automation debt means codified rules do not capture every interpretation. Which of your rules should stay with human interpretation, and why?
What changes in a team when a norm can only be altered through a visible proposal and review?

Written exercise

Exercise · 30 minutes

A team norms file and a lessons-learned entry

Working as a team, write a team norms file in structured form for a real or representative team in your own organisation. Include working agreements, review expectations with a response time, how decisions are made, and two cultural principles each tied to a behavioural example. Then write one lessons-learned entry for a real event: an identifier, a title, the context, what happened, the lesson, the related decision record or system, and tags for search. State which fields a pipeline should require. Hand both files to another team as a simulated pull request; the reviewers propose one change to a norm and record their reasoning, and the authors accept or contest it in writing.

Deliverable: A structured team norms file, one lessons-learned entry with required fields marked, and the written review exchange on one proposed change.

Your work

Self-test

Choose an answer to see whether it is right, or open the answer below each question.

Which three elements make up the shared DNA of the soft as-code disciplines?
Show the answer
D. Structured representation, version control and automatability
The chapter names structured representation, version control and automatability as the common DNA into which soft artefacts are converted.
Which role does the chapter assign to Documentation as Code in the interplay?
Show the answer
B. The communication layer
Documentation as Code is the communication layer, providing narratives around rules and architecture, self-service and feedback loops. Compliance as Code is the quality engine and Architecture as Code the hub.
In Scenario 1, the compliance team updates a data retention rule in code. What happens next in the chapter's account?
Show the answer
C. The architectural models flag components lacking encryption and a documentation section is generated
After the rule changes, the architectural models flag components lacking encryption, Documentation as Code generates a new section about the requirement, and dashboards notify teams.