Skip to content

Instantly share code, notes, and snippets.

@Nooshu
Created October 7, 2026 22:17
Show Gist options
  • Select an option

  • Save Nooshu/31dff021ee02cfbb67161bc0c0534bf3 to your computer and use it in GitHub Desktop.

Select an option

Save Nooshu/31dff021ee02cfbb67161bc0c0534bf3 to your computer and use it in GitHub Desktop.
How I generated the AGENTS.md file using Cursor AI for my GDS complient frontends blog post.

AGENTS.md — Building UK government services

Practical decision guide for AI coding agents designing, implementing, reviewing, refactoring, and testing UK government digital services.

This file synthesises official guidance into rules an agent can apply. Prefer the linked authoritative sources when this file and upstream guidance diverge.


How to use this file

  1. Decide with the hierarchy in Authority and conflict resolution.
  2. Classify every choice as must, should, or consider (see below).
  3. Prefer Design System + GOV.UK Frontend over inventing UI, unless research shows a justified exception.
  4. Ask “does the user still succeed?” when HTML-only, CSS fails, JS fails, assistive tech, or another channel is in play.
  5. Do not treat this repo (or any template) as assessment-ready by default — assessment readiness is earned through research, accessibility evidence, security, and operational maturity.

Strength of guidance

Label Meaning for the agent
Must Legal duty, Service Standard / TCoP non-negotiable for live users, or explicit “must” in official guidance. Do not ship without it (or a documented, valid exception).
Should Strong official recommendation. Default unless evidence shows a better user outcome and you can justify the trade-off.
Consider Contextual. Use judgement, user research, and constraints (legacy, policy, channel mix). Document the choice.

When official guidance uses “must” / “should” / “can”, mirror that language. Do not harden soft guidance into absolutes.


Authority and conflict resolution

Prefer sources in this order when they overlap:

  1. Law and regulations — Equality Act 2010 / DDA 1995 (NI); Public Sector Bodies Accessibility Regulations 2018 (WCAG 2.2 AA + accessibility statement).
  2. Service Standard and Service Manual — how services must be designed and run for users.
  3. Technology Code of Practice (TCoP) — how technology projects are designed, bought, and assured (including spend controls).
  4. GOV.UK Design System — styles, components, patterns, and when/how to use them (user-facing consistency and researched defaults).
  5. GOV.UK Frontend docs + release notes + fixture HTML — technical contract for markup, CSS, JS, and upgrades.
  6. AI Playbook for the UK Government — when the service uses or is affected by AI.
  7. Government Design Principles — underlying philosophy when no more specific rule exists.
  8. Roadmaps / GitHub project boards — planning signal only; not a licence to ship unreleased chrome.

Community discussions and prototypes are starting points, not contracts. Validate with research for your users before adopting.


What good looks like (north star)

Government services exist so people can do something they need, often with no real alternative. The people who need a service most are often those who find it hardest to use.

Optimise for:

Goal Why it matters
User need first Wrong problem → wasted public money and failed journeys.
Whole journey Users should not need to understand departmental boundaries.
Simplicity Complexity causes errors, cost, and loss of trust.
Inclusion Legal duty + better outcomes for everyone (situational and permanent needs).
Progressive enhancement Networks, devices, browsers, and JS fail; core tasks must still work.
Security & privacy Services hold personal and sensitive data; failure harms people and trust.
Reliability & operations Limited choice of when/how people access government.
Reuse & openness Avoid reinventing solved problems; reduce lock-in; share learning.
Sustainability Digital services consume energy and materials; minimise impact.
Evidence Research and performance data beat assumptions.

Government Design Principles (compressed for decisions): start with user needs; do less; design with data; do the hard work to make it simple; iterate; this is for everyone; understand context; build services not websites; be consistent not uniform; make things open; minimise environmental impact.


Decision sequence (every feature)

Work top-down. Do not jump to UI frameworks or AI because they are available.

1. What user need and whole-problem journey is this for?
2. Is a new digital transaction needed, or would content, API, campaign, or reuse suffice?
3. What constraints are real (law, policy, offline channels) vs assumed?
4. Can Design System patterns/components meet the need?
5. Does HTML-first progressive enhancement cover the core task?
6. What accessibility, privacy, security, and operational risks appear?
7. What evidence (research, analytics, fixtures, tests) will prove it works?
8. Only then: implementation detail (stack, components, JS enhancement, AI).

Service Standard — how it drives code decisions

The Service Standard is the primary product/engineering contract. Translate points into implementation behaviour:

Point Agent implication
1. Understand users and needs Do not invent journeys from assumptions. Prototype to learn; use research and data. Prefer throwaway prototypes early.
2. Solve a whole problem Scope by user mental model, not org chart. Reuse existing solutions (including existing AI) before building. Minimise re-asking for the same data (with privacy respect). Do not design the service around a technology, COTS product, or generative AI.
3. Joined-up channels Online + letters + phone + face-to-face must cohere. Code changes that break offline scripts or letters fail the standard.
4. Simple to use Success first time with minimum help. Match GOV.UK look/feel and content style for GOV.UK services. Test usability often.
5. Everyone can use it WCAG 2.2 AA, assisted digital for non-digital users, research with disabled people and protected characteristics.
6. Multidisciplinary team Implementation must be reviewable by design, content, research, security, ops. If AI is used, someone who understands it must be available to the team.
7. Agile Small releases; avoid contracts/tech that block iteration.
8. Iterate frequently Architecture must allow continuous improvement after go-live, not only bugfixes.
9. Secure + privacy Secure by Design; risk ownership; third-party due diligence; privacy-preserving data handling; security UX that enables journeys rather than blocking them unnecessarily.
10. Success metrics Instrument meaningful outcomes; central government publishes mandatory KPIs. Monitor bias/ethics where relevant, not only uptime.
11. Right tools Cost-effective, exit-friendly, understand total cost of ownership and AI impact on UX/inclusion/decision reliability. Prefer common platforms where appropriate.
12. Open code Publish new code openly by default (minus secrets); justify exceptions.
13. Open standards & common patterns Use Design System / common platforms; contribute useful new patterns; publish non-sensitive data openly when appropriate.
14. Reliable service Uptime, deployability, monitoring, QA not left solely to automation; environments like production; plan for incidents.

Assessment nuance (must vs iterable)

Per Service Manual guidance on applying the standard:

  • Can often iterate after release: imperfect UX, incomplete join-up, content polish — if research continues.
  • Cannot iterate your way out of before real users: accessibility and security/privacy failures; AI used without understanding risks or without meeting identified user needs.

Avoid technology or contract choices that freeze the service so it cannot improve.


Technology Code of Practice — engineering defaults

Use TCoP for all technology work; align with mandatory points for spend control. Practical defaults for agents:

TCoP theme Default stance
User needs Technology follows researched needs, not vendor demos.
Accessible & inclusive Infrastructure and interfaces include everyone; accessibility is not a frontend-only concern.
Open source Prefer open source; publish code; avoid unnecessary proprietary lock-in.
Open standards Interoperability over custom protocols; easier upgrades and exits.
Cloud first Prefer public cloud per policy unless constraints justify otherwise.
Secure Proportionate security across lifecycle; Secure by Design.
Privacy integral Privacy by design; minimise personal data.
Share & reuse Prefer common government components/platforms before building anew.
Integrate & adapt Work with legacy deliberately; plan evolution.
Better use of data Quality, ethics, and reuse — not hoarding.
Purchasing strategy Commercial + technical fit; short enough contracts to allow change; accessibility in procurement.
Sustainable technology Prefer efficient architectures, fewer heavy client bundles, sensible retention.
Meet Service Standard If building a service, TCoP does not replace the Service Standard.

Accessibility and inclusion

Legal / Service Standard baseline (must)

  • Meet WCAG 2.2 Level AA for websites and public-facing apps in scope of the regulations.
  • Publish and maintain an accessibility statement (from public beta for services); keep it findable (typically every page / app store listing / in-app).
  • Work with common assistive technologies (screen readers, magnifiers, speech recognition).
  • Include disabled people in user research.
  • Accessibility is a whole-team duty (content, design, development, research, product).
  • Make non-digital parts accessible too (letters, contact channels, alternative formats).
  • Assisted digital support is separate from accessibility: plan help for people who cannot use the digital service alone.

Why (so agents do not “optimise it away”)

Public services are often compulsory. Inaccessible services exclude people who need them most, breach legal duties, and usually harm everyone (clarity, mobile use, keyboard use, resilience).

Implementation rules agents must follow

  • Semantic HTML and logical source order / heading outline.
  • One clear main h1 per page; do not skip heading levels for styling.
  • Visible focus styles; never remove outlines without an equivalent accessible focus indicator (do not override GOV.UK’s focus treatment).
  • Full keyboard operability for all tasks.
  • Sufficient colour contrast; do not repurpose Design System colours with new meanings.
  • Form errors: error summary + field errors, matching wording; focus management to the summary; Error: prefix in page title when validating.
  • Prefer labels, hints, and accessible names from Design System components over custom ARIA.
  • Do not rely on colour, shape, or position alone to convey meaning.
  • Test with assistive tech for JS-enhanced behaviour; automated checks are necessary but not sufficient.
  • Plan audits before public beta; fix issues early (cheaper than late rework).

Exceptions and nuance (consider / legal process)

  • Regulations list exempt content types (e.g. some legacy PDFs, live AV, certain third-party content). Explain exemptions in the statement; Equality Act reasonable adjustments still apply.
  • Disproportionate burden is a documented legal assessment, not “we ran out of time/knowledge”. Agents must not claim it casually.
  • Schools/nurseries and some bodies have partial/full exemptions from the regulations — still consider Equality Act duties.

Progressive enhancement and frontend architecture

Requirement (must)

All government services must follow progressive enhancement: HTML first, then CSS, then JavaScript as enhancement — even if a parent product uses JS heavily.

Why: CSS/JS fail for many real reasons (network, corporate proxies, extensions, CDN outages, browser bugs, users disabling JS). Core needs must still be met. Semantic HTML also underpins accessibility.

Rules

Layer Rule
HTML Core journeys work with HTML alone (forms, navigation, content). Correct semantics; sensible document outline.
CSS Enhance presentation. Avoid CSS-in-JS that leaves the page unstyled when JS fails. Prefer fault-tolerant CSS.
JavaScript Enhance existing HTML/CSS that already provides the capability (e.g. autocomplete enhancing a native control). Feature-detect; treat JS as non-fault-tolerant.
SPA Do not build the service as a single-page application that owns navigation in JS. Breaks assistive tech context, focus, history, and recovery from network errors.
Client frameworks Should not use a client-side JS framework if the UI is mostly Design System components. If used: justify with user evidence; isolate components so failure is local; keep core tasks HTML-capable.
COTS / suppliers Put progressive enhancement (and accessibility) into requirements and contracts.

If a task truly cannot work without JS, must provide an alternative channel (phone, in-person, etc.) that meets the need.

GOV.UK Frontend technical contract (must / should)

  • Use GOV.UK Frontend (current supported major) as the implementation of Design System styles/components — not deprecated stacks (Elements / Toolkit / old Template) for new work.
  • Prefer Nunjucks macros (or equivalent maintained wrappers) over long-term copy-paste of HTML from the website.
  • When building wrappers in another language: treat official fixtures.json html as the parity contract. Compare your output to fixtures; ignore known framework-only differences deliberately, do not “fix” fixtures to pass.
  • Initialise JS with type="module"; include the supported js-enabled / govuk-frontend-supported snippet; call initAll / createAll for components you ship.
  • Import only the JS you need in production builds for performance, but ensure every interactive component you render is initialised.
  • Respect browser support grades (A/B/C/X). Grade X (no type="module", including IE) must still get usable HTML/CSS; Frontend JS will not run.
  • Keep CSS via the supported Sass/@use pipeline (Dart Sass); do not treat precompiled CSS as the long-term customisation story if you need overrides.
  • Do not restyle GOV.UK primitives ad hoc (buttons, input borders, colour meanings).
  • Serve over HTTPS with HSTS; do not hotlink assets from GOV.UK or other services (URLs change).
  • Before upgrading Frontend: read releases and Design System “What’s new”; treat breaking changes as migration work with fixture re-checks.

Component lifecycle (should)

  • Prefer Stable Design System components/patterns.
  • Trial (and experimental community work): may be used to learn, with clear awareness they can change; contribute research back; do not treat as frozen API.
  • Do not ship unreleased Design System chrome from roadmaps/boards as if it were production guidance.

Design System — UI and content decisions

Defaults (should / must where noted)

  • Use styles for layout, typography, colour, images — look and feel like GOV.UK.
  • Use components for reusable UI (inputs, navigation, tables, etc.).
  • Use patterns for tasks (question pages, addresses, accounts, validation). Patterns compose components; they are not new low-level widgets.
  • Read each component/pattern’s “when to use” / research notes before adapting.
  • Be consistent, not uniform: same language and patterns where possible; adapt when evidence demands; share improvements back.

Question pages and forms (high-frequency rules)

Must / should:

  • Know why each question is asked; only ask what you need (question protocol).
  • Never mark required fields with asterisks; mark optional fields with “(optional)” on label/legend.
  • Question pages include back link, page heading, continue action (novalidate on forms using Design System validation patterns).
  • Prefer one thing per page unless research supports combining.
  • Do not use back link and breadcrumbs together.
  • Allow “I do not know” / “I’m not sure” when valid.
  • Do not re-ask for the same information in one journey; pre-populate or offer reuse.
  • On errors: error summary at top of main (below back link/breadcrumbs, above h1), plus field errors; same wording in both places; link to the right control (first errored field in a group).
  • Retain user-entered values after errors.
  • Prefer plain text component options; treat HTML options as trusted/sanitised only.

Content

  • Follow GOV.UK style for GOV.UK services (plain English, clear error messages, clear reasons for questions).
  • Content design is part of accessibility and completion rates — not decoration.

Custom components

Should avoid creating new low-level components when Design System ones exist. If you must:

  • Start from existing components/patterns and research.
  • Meet accessibility and progressive enhancement bars.
  • Share publicly (Service Standard point 13) when reusable.
  • Add inset text / clear explanation when using something outside Design System norms so users and assessors understand risk.

Security, privacy, and trust

Must:

  • Threat-model early; maintain risk assessment through the lifecycle.
  • Secure by Design / government cyber expectations; proportionate controls.
  • Collect/process/store personal data lawfully and minimally; privacy is integral, not a bolt-on.
  • Due diligence on third-party software and integrations.
  • Protect sessions, secrets, and admin interfaces; never commit credentials.
  • Cookies/similar tech: follow Service Manual rules; do not surprise users.
  • Frontend hardening (e.g. CSP): allow the GOV.UK Frontend inline snippet via hash/nonce correctly; do not weaken CSP casually.
  • Security processes must be usable — research them; avoid controls that push users into unsafe workarounds.

Should:

  • Regular dependency updates and vulnerability testing.
  • Separate asset hosting concerns thoughtfully (performance vs cookie scope) without breaking HTTPS assumptions.

Performance, resilience, and operations

Why: Slow or down services exclude carers, people on poor networks, and anyone with limited time windows. Heavy client JS harms lower-powered devices.

Should:

  • Minimise JS/CSS weight; server-render HTML; enhance progressively.
  • Measure frontend performance; test on low-end devices and constrained networks.
  • Automate deployments with minimal downtime; keep prod-like pre-production environments.
  • Monitor availability and user outcomes (including bias/ethics where automated decisions exist).
  • QA is a team responsibility — automation helps but does not replace exploratory/human QA.
  • Prefer efficient implementations (sustainability + performance align).

Must (reliability mindset): Have a proportionate incident response plan; do not design systems that only specialists can operate.


Using AI in services

Apply the AI Playbook and Service Standard AI updates together.

Must:

  • Only use AI when it meets an identified user need — not because it is novel.
  • Understand limitations (no guaranteed accuracy; bias; hallucination; security threats such as prompt injection / data poisoning where relevant).
  • Use AI lawfully, ethically, responsibly; engage legal, data protection, and assurance early.
  • Keep meaningful human control at the right stages; high-risk decisions need human validation.
  • Secure AI systems; do not leak personal data into models/prompts inappropriately.
  • Ensure team access to expertise that understands the AI and its impact.
  • Be open: label automated responses; use ATRS where required for algorithmic transparency.

Should:

  • Prefer non-AI solutions when they are simpler and sufficient (Playbook: right tool for the job).
  • Monitor drift, bias, and quality in live operation.
  • Reuse cross-government approaches; collaborate rather than siloing models.
  • Assess environmental cost of training/inference.

Consider: Design System roadmap items on AI-in-service patterns are exploratory — wait for published patterns where possible; research any interim design.


Openness, reuse, and maintainability

Should / must as marked:

  • Must (default): New source code open and reusable under appropriate licences; explain exceptions (e.g. unannounced sensitive policy).
  • Prefer open standards and common platforms (Pay, Notify, One Login, Design System, etc.) over bespoke.
  • Publish useful non-personal, non-sensitive data openly when appropriate.
  • Design for exit: avoid lock-in that prevents iteration (contracts, proprietary formats, framework traps).
  • Manage dependencies deliberately; keep Frontend and critical libs current enough to receive fixes.
  • Document decisions that affect assessors and future teams (especially exceptions to Design System or PE).

Working with upstream Design System change

Roadmaps and GitHub org project boards (e.g. Design System team boards) show intent. They change.

Should:

  • Watch Design System roadmap and govuk-frontend releases.
  • Plan migrations (Sass module changes, new components, brand refreshes) rather than forking forever.
  • Feed research back via Design System community channels when you learn something reusable.

Must not:

  • Depend on unreleased components as if stable.
  • Copy experimental GitHub discussion HTML into production without research and accessibility review.

Practical playbooks for agents

When implementing a page

  1. Identify the user task and relevant pattern.
  2. Compose components (macros/wrappers), not pasted markup.
  3. Ensure page template / chrome: skip link, phase banner if needed, header/footer, language if applicable.
  4. One h1; back link or breadcrumbs.
  5. Forms: novalidate, labels/hints, optional marking, error summary pattern.
  6. HTML-only success path; then CSS; then GOV.UK Frontend JS modules.
  7. Content in plain English; explain why you ask.
  8. Security headers and HTTPS assumptions intact.
  9. Check WCAG risks (name, role, value, focus, errors, contrast).
  10. Add or update tests (fixture parity for wrappers; journey tests for pages).

When reviewing a PR

Flag as blocking if any of these are true:

  • Core task requires JS/SPA navigation without an alternative.
  • Custom component duplicates Design System without justification.
  • Missing error summary/field errors or inaccessible error wiring.
  • Focus styles removed; keyboard traps; missing names/labels.
  • Personal data logged or exposed; secrets committed.
  • Accessibility or security regressed for real-user release.
  • AI feature lacks human oversight / user-need justification / transparency.

Flag as should-fix if: unnecessary client framework, oversized bundles, re-asking data, inconsistent GOV.UK content style, skipped research notes on a pattern deviation.

When tests fail fixture HTML

  • Fix the wrapper/implementation, not the fixture.
  • Re-read macro options and escaping behaviour.
  • After Frontend upgrades, expect intentional HTML changes — update implementation to match new fixtures.

When stuck without explicit guidance

  1. Re-read the relevant Design System pattern/component page.
  2. Apply Service Standard points 1, 4, 5, 9, 13 and progressive enhancement.
  3. Choose the option that maximises successful completion for the widest set of users with the least lock-in.
  4. Record the assumption and what research/data would validate it.

Quick checklist (ship / review)

Copy and mentally tick before finishing a change:

  • User need and journey context understood (not org-chart scoped)
  • Design System pattern/component used (or justified exception)
  • Works with HTML only for the core task; no SPA navigation
  • GOV.UK Frontend correctly integrated (CSS, assets, type="module JS, init)
  • WCAG 2.2 AA risks addressed; errors and focus correct
  • Privacy/security sensible; no secrets; HTTPS/HSTS posture preserved
  • Content clear; only necessary questions; optional fields marked correctly
  • Performance reasonable on low-end / poor network
  • Monitoring/operability not made worse
  • AI (if any): needed, supervised, transparent, lawful
  • Open/reuse posture preserved; fixtures/tests updated
  • Exceptions documented with rationale

Authoritative sources

Topic URL
GOV.UK Design System https://design-system.service.gov.uk/
Design System roadmap https://design-system.service.gov.uk/community/roadmap/
Design System team boards (planning detail) https://github.com/orgs/alphagov/projects/43 · https://github.com/orgs/alphagov/projects/53
GOV.UK Frontend releases https://github.com/alphagov/govuk-frontend/releases
GOV.UK Frontend docs https://frontend.design-system.service.gov.uk/
Testing HTML / fixtures https://frontend.design-system.service.gov.uk/testing-your-html/
Service Manual https://www.gov.uk/service-manual
Service Standard https://www.gov.uk/service-manual/service-standard
Service assessments https://www.gov.uk/service-manual/service-assessments
Progressive enhancement https://www.gov.uk/service-manual/technology/using-progressive-enhancement
Technology Code of Practice https://www.gov.uk/guidance/the-technology-code-of-practice
Accessibility regulations guidance https://www.gov.uk/guidance/accessibility-requirements-for-public-sector-websites-and-apps
Making services accessible https://www.gov.uk/service-manual/helping-people-to-use-your-service/making-your-service-accessible-an-introduction
Government Design Principles https://www.gov.uk/guidance/government-design-principles
AI Playbook for the UK Government https://www.gov.uk/government/publications/ai-playbook-for-the-uk-government/artificial-intelligence-playbook-for-the-uk-government-html

When sources conflict, follow Authority and conflict resolution. When this file conflicts with those URLs, the URLs win — update this file in a later change.

Take all of the links below and research them thoroughly, including relevant pages, guidance, standards, and documentation they link to.
Use this research to create a comprehensive but succinct AGENTS.md file that provides an AI coding agent with the context it needs to build high-quality UK government services.
Do not simply summarise each source. Instead, synthesise the guidance into a coherent set of principles, rules, constraints, and recommended approaches that an agent can apply when making implementation decisions.
The AGENTS.md file should:
* Explain what an agent should do, but also why the guidance exists, particularly where it relates to user needs, accessibility, inclusion, progressive enhancement, performance, security, resilience, and maintainability.
* Combine technical and non-technical guidance so that implementation decisions are informed by the wider principles of designing and delivering UK government services.
* Consider different perspectives on the same problem, including user experience, design, accessibility, engineering, content, security, operations, and service delivery.
* Distinguish between requirements, strong recommendations, and contextual guidance.
* Prefer official and authoritative UK government guidance where sources overlap or conflict.
* Preserve important nuance and exceptions rather than turning guidance into absolute rules where none exist.
* Translate guidance into practical instructions that an AI coding agent can follow while designing, generating, reviewing, refactoring, and testing code.
* Include enough context for the agent to make sensible decisions when it encounters situations that are not explicitly covered.
* Avoid unnecessary duplication, lengthy quotations, and generic software engineering advice that is not relevant to building UK government services.
* Structure the file so that important instructions are easy for an AI agent to locate and apply.
The final AGENTS.md should act as a practical decision-making guide, not simply a summary of the source material. Its purpose is to help an AI coding agent understand the standards, principles, constraints, and reasoning behind how good UK government services should be built.
Sources:
https://design-system.service.gov.uk/
https://design-system.service.gov.uk/community/roadmap/
https://github.com/orgs/alphagov/projects/43
https://github.com/orgs/alphagov/projects/53
https://github.com/alphagov/govuk-frontend/releases
https://www.gov.uk/service-manual/service-standard
https://www.gov.uk/service-manual
https://www.gov.uk/service-manual/service-assessments
https://www.gov.uk/guidance/the-technology-code-of-practice
https://www.gov.uk/guidance/accessibility-requirements-for-public-sector-websites-and-apps
https://frontend.design-system.service.gov.uk/
https://frontend.design-system.service.gov.uk/testing-your-html/
https://www.gov.uk/service-manual/technology/using-progressive-enhancement
https://www.gov.uk/government/publications/ai-playbook-for-the-uk-government/artificial-intelligence-playbook-for-the-uk-government-html
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment