AFDOCS — AI-Friendly Documentation Standards
A set of documentation standards designed to be both human-readable and AI/LLM-parseable, for systems that span multiple repositories, infrastructure, and application components.
Standards
| Standard | File | Description |
|---|
| AFADS | AFADS.md | AI-Friendly Architecture Documentation Standard — how to document system and component architecture |
| AFOPS | OPS-STANDARD.md | AI-Friendly Operational Procedures Standard — how to document operational procedures (deployments, backups, maintenance, etc.) |
| AFPS | AFPS.md | AI-Friendly Programming Standard — how to document and enforce coding conventions, patterns, and development practices |
| AFSS | AFSS.md | AI-Friendly Security Standard — how to document security controls, policies, threat models, and security review processes |
| AFCS | AFCS.md | AI-Friendly Compliance Standard — how to document compliance mappings, risk assessments, and compliance scoring against external frameworks (OWASP, NIS2, etc.) |
| AFRS | AFRS.md | AI-Friendly Roadmap Standard — how to document roadmaps, technical debt, security improvements, and track progress on initiatives |
Design Goals
- Documentation that AI sessions can parse without prior context
- Structured metadata (YAML) for machine-readable discovery
- Consistent format across repositories and teams
- Composable — procedures, components, conventions, and controls reference each other by stable IDs
- Fail-safe operational procedures with explicit rollback and escalation paths
- Coding conventions that are the source of truth for linter and formatter configs
- Traceable security controls that map to threats, policies, and verification steps
- Quantifiable compliance coverage with traceability from external frameworks to security controls
- Traceable roadmaps connecting planned work to components, security controls, and compliance gaps
How They Fit Together
AFADS defines where documentation lives and how to describe architecture (components, dependencies, deployment topology, ADRs). AFOPS extends AFADS by defining how to write the operational procedures that keep that architecture running (deployments, backups, scaling, patching). AFPS defines how to document and enforce coding conventions, patterns, and development practices — the source of truth from which linter configs and CI checks are derived. AFSS defines how to document security controls, policies, and threat models — connecting threats to verifiable controls at every layer. AFCS defines how to map AFSS controls and policies to external compliance frameworks (OWASP, NIS2, etc.), providing checklists, risk matrices, and compliance scorecards. AFRS defines how to plan and track work through roadmaps, technical debt registries, and security improvements — connecting planned work to components (AFADS), procedures (AFOPS), conventions (AFPS), security controls (AFSS), and compliance gaps (AFCS).
All six standards share the same component_id namespace (from AFADS) and reference each other by stable IDs: AFOPS procedures verify AFSS controls, AFPS patterns implement AFSS controls in code, AFSS controls reference AFOPS procedures for operational verification, AFCS mappings trace external compliance requirements to AFSS controls and policies, and AFRS roadmap items reference components, controls, procedures, and compliance requirements to ensure planned work is traceable end-to-end.
All standards are designed so an AI agent starting a new session can discover, read, and act on the documentation without institutional knowledge. An AI agent can assess compliance posture by reading AFCS mappings and scorecards, generate progress reports from AFRS roadmaps, and trace any gap back to the specific AFSS control, AFOPS procedure, or AFRS roadmap item that needs attention.
Usage
The examples below show how to prompt an LLM to apply AFDOCS standards. Each prompt is designed to be copy-pasted into a new session. Replace placeholders (<…>) with your actual values.
New Repository
Bootstrap AFDOCS documentation for a project from scratch:
Read the AFDOCS standards at https://github.com/securitymonster/afdocs — specifically
AFADS.md, AFPS.md, AFSS.md, AFOPS.md (OPS-STANDARD.md), AFCS.md, and AFRS.md.
This is a new <language/framework> project called <project-name>.
Set up the AFDOCS documentation structure:
1. Create docs/index.md (documentation hub) per AFADS
2. Create docs/component.md describing this component
3. Create the initial YAML registries (components.yaml, conventions.yaml,
procedures.yaml, controls.yaml, frameworks.yaml, roadmaps.yaml)
4. Scaffold placeholder files for conventions, procedures, and security controls
5. Create docs/roadmap/ with an initial feature roadmap or technical debt
registry per AFRS
