knowledge-as-code
Knowledge as Code (KaC) keeps your engineering knowledge in git, where people and AI coding sessions can both find it.
Standards, decisions, runbooks, known fixes and the glossary each become a record: a Markdown document with a
declared type, reviewed by pull request like any other change.
kac is the command-line tool that checks every record against the schema its type declares. It reports each fault
against the file that caused it, and a broken cross-reference fails CI. It writes the indexes nobody should keep by
hand. It also packages the records as a Claude Code plugin, so an agent can look up a standard before it writes
code.
A repository of records, with the schema it runs, is a corpus. People read it as a wiki. Agents read the plugin,
built from the same files, so nothing has to be kept true twice.
An agent writes back by filing an issue on your tracker. A person decides whether what it found becomes a record.
Why use it
- Knowledge gets written down. What one person remembers, or an old chat thread says, becomes a record anybody can
find by its type and its id.
- You can tell whether to trust a record. Each one has an owner, a status and a review date, so you can see who
is responsible for it and whether it is current.
- Agents build to your rules. A session looks up the standard that applies and cites the rule it followed, such as
std-SECRET.STORE.
- Teams share one set of rules. A team's corpus can consume an organisation's corpus, so a standard written once
applies in every repository that takes it.
Compared with alternatives says what KaC adds to a
CLAUDE.md, an organisation's managed instructions, a documentation server or a wiki, and when one of those is enough.
A record, and what kac validate reports
This is a standard from examples/engineering, cut short.
kac checks the frontmatter against the schema for standard. Each heading under ## Rules becomes one rule an agent
can search and cite.
---
id: std-SECRET
type: standard
tier: normative
status: draft
implements: [ pol-SCRT.STORE, pol-SCRT.EMBED ]
applies-to:
- all
review-by: "2027-08-26"
owner: human:paul.law
---
# A secret is read from the store at run time
## Rules
### A secret comes from the store
- A service **MUST** read every secret from the managed store, through an identity granted to the workload.
A type, such as a standard or a runbook, declares its fields and rules in a YAML file under .schema/. Adding a
type to your corpus means adding a YAML file. kac itself does not change.
When a record breaks its schema, kac validate reports the file, the check and the line, and exits 1:
services/catalogue-web.md
error [link-resolves] link target 'missing-runbook.md' does not resolve. (services/catalogue-web.md:76)
validated 28 document(s) and 9 template(s), skipped 0 without frontmatter. 1 error(s), 0 warning(s)
Get started
You need the .NET 10 SDK and git.
dotnet tool install --global KnowledgeAsCode.Tool
mkdir my-corpus && cd my-corpus
kac new # asks what the corpus is called and which types it adopts, each with a default
kac validate # checks every record against the schema its type declares
kac new writes the framework files and a .corpus.yaml that names your corpus. It runs generate and validate,
then stages what it wrote. The first commit is yours to make.
To give the corpus to an agent, build the plugin:
kac export # writes the records out as data under .dist/export/
kac bundle # packages that export as a Claude Code plugin under .dist/plugin/
bundle ends by printing the command that adds the plugin to Claude Code.
Read next:
- Use it shows you how to install the tool, run it over a corpus,
wire it into CI and build the plugin.
Getting started is its first page.
- The framework explains how the types are laid out, where
they came from, and how to write a record.
- Schema reference covers the keys a type file takes, the
rule expression grammar, the checks and the export contract.
examples/ has worked corpora. Read them to see real records, and start your own with
kac new.
Later, kac update takes a newer framework. It leaves
every change in the working tree, so git diff is your review.
Maturity
Early. The tool is tested and published on nuget.org, below
1.0.0 because its commands may still change shape.
The set of types is the part least proven. examples/library and
examples/engineering record which types have met real content.
Every document here describes what exists today, except
Design intent, which states the direction. The
issue tracker lists everything considered and not yet built.
Opinions
Stated openly, because each one shapes the design:
- Azure DevOps wiki is the primary publishing target. Frontmatter renders as a metadata table there,
.order
drives navigation, and /-rooted links resolve from the corpus root. Everything degrades to plain markdown elsewhere,
but the sharp edges were filed against ADO.
- The taxonomy may be too large. It is the most likely thing to be wrong here. The mitigation is a decision table,
and a standing willingness to merge types that are not earning their place.
- Trust matters more than coverage. The failure mode of a wiki is not too little content. It is content nobody
believes. Generated indexes, validated links and immutable decisions all serve that.
- You own the content, and install the tool. An organisation adopting this gets its own copy of the schema and the
documentation, free to diverge.
kac arrives from nuget.org as a version they pin.
Contributing
Pull requests open once kac reaches version 1.0.0. Until then, an issue is the way to help: a bug, a question or a
correction is welcome, and each one is read.
Contributing to kac says what a pull request
owes and which checks gate it. To publish a version of your own,
Forking kac lists what to replace.
This repository contains the tool, the framework a corpus receives, the corpora that prove both, and the trials that
measure its documentation.
| Path | What it contains |
|---|
tooling/ | kac, and the tests behind it |
.schema/ | the schema for every type, read by every corpus in this repository |
template/ | the framework documentation, plugin tree and pages a corpus starts from |
manifest.yaml | which files a corpus receives, and where each one lands |
examples/ | the worked corpora, which CI validates on every commit |
docs/ | the documentation site |
trials/ | repeatable experiments on the documentation, with every run kept |
Run the tool this checkout contains from inside one of the example corpora:
cd examples/library
dotnet run --project ../../tooling/kac -- validate
To change kac, read:
Licence
Released under the MIT licence, so that any organisation adopting this keeps an unencumbered copy.
