Skip to main content

Documentation vs Executable Standards

Most organizations already have:

  • Confluence pages
  • Architecture diagrams
  • Coding standards
  • Development guidelines

The problem is that these documents are written for humans.

AI systems cannot reliably interpret pages of architectural prose.

For example:

Developers should consider whether a component
fits within our Atomic Design methodology.

This is documentation.

A skill turns this into an instruction:

Before generating a component:

1. Determine whether it is an Atom,
   Molecule, Organism, Template or Page.
2. Generate missing lower-level components first.
3. Compose larger components afterwards.

This is executable guidance.

The difference is critical.

Mini Exercise​

Take one vague team guideline from your own project or invent one.

Rewrite it as a numbered instruction list an AI agent could execute step by step.

Example​

Vague guideline:

Use Atomic Design for new UI work.

Executable version:

1. Classify the new UI element as Atom, Molecule, Organism, Template, or Page.
2. Check whether a lower-level component already exists before creating a new one.
3. Create missing lower-level components first.
4. Compose the higher-level component only after its dependencies exist.