Chapter Authoring Guide

This guide is the operational checklist for anyone drafting or revising a chapter of AI Developer, whether a human contributor or an AI-assisted writer. Read BOOK_BLUEPRINT.md for the chapter brief, SERIES_FOUNDATIONS.md for the conclusions of Books 1–11 it builds on, DISPOSITION.md for the fixed design of the book, EXAMPLE_ORGANISATIONS.md for the development profiles of Nordvik Region and Hansa Mutual, AUTHOR_PERSONA.md for voice, and STYLE_GUIDE.md for language rules before writing.

File layout

  • Chapter file: docs/NN_short_name.md, where NN is the two-digit chapter number from book_index.json.
  • Diagram source: docs/images/diagram_NN_topic.mmd. The rendered docs/images/diagram_NN_topic.png is produced by python3 scripts/check_mermaid_diagrams.py --write-missing and committed alongside the source.
  • No YAML front matter. The first content line is the H1 title with a Pandoc anchor: # Title {#anchor}.

Required structure

# Chapter Title {#chapter-anchor}

Opening paragraph that states what the chapter covers, why it matters to the reader and which of the five developer functions it concerns (for example **D3 Build** and **D4 Prove**).

![Alt text describing the diagram](images/diagram_NN_topic.png)

*Figure NN.1: One-sentence caption.*

## First major section

Prose. Use ### subsections where they improve clarity.

## Further sections ...

## The debate                       (Chapters 8, 13, 20 and 29 only; see rule 16)

### The case for concern

### The case for calm

### Where the positions meet

### What can be done

## Verdict                          (chapters with a debate only)

### Across the usage modes          (or ### Across the degrees of delegation)

### Nordvik Region and Hansa Mutual

## Summary

Three to five paragraphs that recap the chapter, name the developer functions it concerns and point to the next chapter.

## Sources

1. **Author, A. (Year).** *Title.* Publisher. ([N, Author, Year](36_references.md#source-N))

Rules

  1. Language. Oxford-standard British English. Headings in sentence case except for proper nouns, the terms AI Architecture and Architecture as Code, and the names of the five developer functions and the autonomy levels. Every heading starts with a capital letter. No em-dashes in prose; use a colon, a comma or a new sentence.
  2. Length and weighting. Measured as prose (excluding code blocks and tables): numbered narrative chapters 3,600 to 6,000 words, unless the brief says otherwise (Chapters 1 and 4: 4,500 to 6,000). A chapter far below the range should be expanded with substance, not padding. A chapter that grows beyond about 6,000 words, or a section beyond about 2,500 words that treats a distinct subject, is split into a companion chapter.
  3. Diagrams. At least one Mermaid diagram per chapter. Use graph, flowchart, sequenceDiagram, quadrantChart, mindmap, or classDiagram. Apply Kvadrat classes (:::kv-primary, :::kv-accent, :::kv-highlight, :::kv-muted, :::kv-pattern) to key nodes. No emojis. Labels in British English. Keep node text short so that diagrams render at 1400 by 900 pixels. Do not use quotation marks inside node labels unless necessary, and avoid parentheses in labels (use square-bracket node syntax with plain text). Diagrams show people as roles (regional director, chief executive, unit manager, works council), never as faces or caricatures.
  4. Code. At least one fenced code block with a language identifier (yaml, json, python, bash, rego, sql). YAML and JSON must parse. Keep examples under 60 lines; longer versions belong in Appendix A.
  5. Citations. Cite only sources that exist in 36_references.md, in the form ([N, Author, Year](36_references.md#source-N)), which renders as (N, Author, Year). Run python3 scripts/format_citations.py --fix to derive the author label and year from the bibliography; see STYLE_GUIDE.md for the label rules. Do not invent sources. Do not add entries to 36_references.md from a chapter branch; propose additions to the editorial team instead. Verify every article number, recital and judgment against its live text (EUR-Lex for EU law, the official national gazette or court database for national law and case law) before citing it, and list in your report every claim you could not verify.
  6. Sources section. The final section is ## Sources, a numbered list, one entry per cited source, in the format shown above, with the source link at the end of each entry.
  7. Europe first. Include at least one concrete European or public-sector consideration. Attribute legal statements to the instrument and article (for example NIS 2 Articles 20, 21 and 23; DORA Articles 5, 17 to 19 and 28 to 30; GDPR Articles 32 to 34; AI Act Articles 12, 14, 26, 72 and 73; Regulation (EU) 2023/2854 (the Data Act), Chapter VI. In this book "DORA" always means Regulation (EU) 2022/2554). Frame them as organisational and architectural implications, not legal advice. Where national law differs, say which member state's law the example uses.
  8. Codify it. Show at least one artefact that belongs in version control.
  9. Practical guides. Where a chapter prescribes measures, include at least one practical guide the reader can follow: a ### Practical guide: <task> subsection with the purpose, the roles involved (developer, tech lead, engineering manager, architect, platform engineer, tester, product owner, works-council member, data protection officer, public-sector IT lead), the inputs, the steps and the artefact that results.
  10. Worked examples in the chapter. Show, do not only tell. Where a chapter recommends an artefact (a delegation profile, a mandate manifest, a specification record, a code-ownership record, a verification plan, a review record, an agent run record, a provenance record, an adoption and value record, an apprenticeship plan, a competence record, an AI Decision Record), show a worked example for Nordvik Region or Hansa Mutual that agrees with docs/EXAMPLE_ORGANISATIONS.md, and add a ### Nordvik Region and Hansa Mutual subsection before the Summary.
  11. Five developer functions as red threads. Chapter 4 defines the five functions of the developer loop, and every chapter in Parts II to V uses them by these exact names in its opening and its Summary: D1 Frame (problems, requirements, intent, specification); D2 Design (architecture, interfaces, constraints, decisions); D3 Build (writing and directing the making of code, within a mandate); D4 Prove (review, tests, verification, secure code, with an oracle independent of the generator); D5 Steward (release, operation, maintenance, ownership, incidents and the authority to revert). Parts I, VI and VII frame and conclude all five. Every narrative chapter also has an ### Across the usage modes or ### Across the degrees of delegation subsection, normally a compact table, with the Level 4 prohibitions where they apply, and says who owns the change (Name, Understand, Revert) wherever AI took part in a change that reaches production.
  12. Observable, expected, speculation. Every statement about the future of the developer role, of work or of the technology carries one of the three labels of AI Governance, Chapter 22: observable (happening now and documented), expected (supported by a stated trend or a decided instrument) or speculation (plausible but unevidenced). The author's own projections appear only in Chapters 29 and 33 and are labelled. No chapter says that a tool raises productivity, that code is secure, that a team is AI-fluent or that a role is redundant without saying what was measured, how, when and with what result.
  13. Cross-references. Refer to other chapters of this book as "Chapter N". Refer to the earlier volumes in plain text, without a link, as "Architecture as Code (Chapter N)", "AI Governance, Chapter N", "AI Platform and Security, Chapter N", "AI Red Team, Chapter N", "AI Threat, Chapter N", "The Transformed Security Architect, Chapter N", "AI Boss, Chapter N", "AI Blue, Chapter N", "AI Purple, Chapter N", "AI Operations, Chapter N" and "AI Leader, Chapter N", using the tables of contents in SERIES_FOUNDATIONS.md, and cite them as (Nordqvist, 2025) for Architecture as Code or (Nordqvist, 2026) for Books 2–11. Summarise just enough of an earlier volume's content that the reader is not left with a gap, and state explicitly when a chapter builds on a conclusion recorded in SERIES_FOUNDATIONS.md (the numbered conclusions F1 onwards). The series builds strictly in publication order, so that there is no circular reasoning between the books: Architecture as Code (Book 1) refers to no other volume, AI Governance (Book 2) only to Book 1, AI Platform and Security (Book 3) only to Books 1–2, AI Red Team (Book 4) only to Books 1–3, AI Threat (Book 5) only to Books 1–4, The Transformed Security Architect (Book 6) only to Books 1–5, AI Boss (Book 7) only to Books 1–6, AI Blue (Book 8) only to Books 1–7, AI Purple (Book 9) only to Books 1–8, AI Operations (Book 10) only to Books 1–9, AI Leader (Book 11) only to Books 1–10, and AI Developer (Book 12) only to Books 1–11. Never refer to a later volume. Every new claim either cites an external source or is the book's own conclusion, drawn in a conclusions section or summary; a reference to an earlier volume builds on that volume's conclusions and never stands in for an external source for a factual claim. tests/test_series_references.py enforces the order.
  14. Defensive and constructive. Describe threats and failures by mechanism and outcome at the level needed to design controls and tests; never include exploit code, malware, payloads, jailbreak or injection strings, or step-by-step attack instructions. Never describe covert monitoring of staff or the defeat of employee representatives' rights as a method. Describe effects on people by what studies measured.
  15. Voice. No marketing language, no hype, no anthropomorphism, no rhetorical questions as transitions, no filler openers. Active voice, imperative mood for instructions. Describe developers, leads, managers, staff and representatives with respect: never call anyone lazy, stupid or replaceable, and never portray developers as obsolete.
  16. Constructive debate. Chapters 8, 13, 20 and 29 each contain a debate section with four subsections, in this order: ### The case for concern (the strongest version, in the words and with the evidence of those who hold it), ### The case for calm (the strongest sceptical or optimistic version, treated with the same charity), ### Where the positions meet (the facts and measures both sides accept), and ### What can be done (concrete actions for developers, tech leads, engineering managers, leaders and representatives). It is followed by a verdict that labels the outlook observable, expected or speculation and states what people and organisations can influence. State each position at its strongest; never caricature a position or use labels in place of an argument. Separate what a source reports from interpretation: say what was measured, in whom, over what period and with what method before saying what it means. Keep the author's own projections for Chapters 29 and 33, and end every chapter with something the reader can do. Other chapters may stage a shorter debate in the same form where the brief asks for one.
  17. No anthropomorphism, and "decides" only where a decision was delegated. An AI system suggests, generates, drafts, refactors, reviews or executes within a mandate; it does not want, understand, intend or decide. Write "the assistant generated the function" or "the agent opened the pull request"; write "decides" only for a system to which a decision was formally delegated, and then say who delegated it.
  18. Sources the book has not yet verified. The seed bibliography (docs/36_references.md) is carried over from earlier volumes and its entries were verified there. Before a chapter cites a source on software development research, developer productivity, code security and supply chain, intellectual property, employment and labour law or public procurement, add the entry to the bibliography in the chapter's reserved range (N100+1 to N100+49), open it, check it against the primary text or a bibliographic record, and state what it measured. Drop any claim that cannot be verified. Facts about law, studies and cases marked [verify] in DISPOSITION.md are checked against the live text at eur-lex.europa.eu or the primary source.

Before you submit

python3 -m pytest tests/test_completeness.py tests/test_consistency.py tests/test_reference_consistency.py -q
python3 scripts/check_mermaid_diagrams.py --write-missing
python3 scripts/audit_references.py