Decisions get buried
Architecture rationale lives in Slack threads, PR comments, and someone's head. No tool can find it.
An open standard for making company knowledge and taste consumable by agents.
knowledge/ is a directory and a convention for the decisions, context, and reasoning that never make it into code. It lives in your repository, it is plain markdown, and any tool that reads files can read it. Adopt it today with no account and nothing installed.
APACHE 2.0|VERSION 0.2.0|PUBLISHED MARCH 2026 BY CODESPEED
Every AI tool has the same blind spot.
Model quality stopped being the constraint a while ago. The reasoning behind your architecture, the promises your product cannot break, and the taste your team argued its way to were never written anywhere a model can read, so even the best one available is guessing at them.
What one agent learns stays on one machine
Newer tools do write memories, but they land in one person's setup. Nobody else's agent can read them, and nobody can review or govern what got written.
Agents suggest rejected patterns
Without knowing your decisions, AI tools keep proposing approaches your team explicitly ruled out.
The Protocol
One directory and one convention, readable by any tool you already use.
Markdown files. In your repo. That's it.
No proprietary formats, no external database, and no sync problem. Knowledge sits next to the code it describes and versions with Git.
Optional frontmatter for structure
Add YAML frontmatter when structure earns its keep. Tools that understand it can flag stale knowledge, and tools that do not still get readable markdown.
Directory Structure
📁knowledge/
📄README.mdRouting table: "what to read" index
📁decisions/Why we chose what we chose
📄2026-02-10-auth-strategy.md
📄2026-01-15-database-choice.md
📁architecture/How the system is designed
📄overview.md
📄data-model.md
📁conventions/How we write code
📄error-handling.md
📄testing-strategy.md
📁context/Domain knowledge and business logic
📄customer-experience.md
📄domain-glossary.md
📁api/API documentation
📁archive/Superseded docs, never deleted
Inside README.md
A lookup table mapping questions to documents. Instead of scanning every file, an agent looks up what it needs and gets pointed at the right doc.
README.md
| "What are we building?" | architecture/overview.md |
| "Why Postgres?" | decisions/2026-01-15-database-choice.md |
| "How do we handle errors?" | conventions/error-handling.md |
| "What does ‘tenant’ mean?" | context/domain-glossary.md |
Get Started
Start in five minutes.
Every level is useful. Start small, add structure as your project grows.
1
One file
5 MINUTES
Create the directory and a README with a routing table and your key decisions.
mkdir knowledge # Create README.md with: # - Project overview (2-3 sentences) # - Routing table (questions → docs) # - Key decisions and why
2
Add decisions
30 MINUTES
Create a decisions/ folder. Document your most important technical choices. Focus on the why.
knowledge/
decisions/
2026-02-10-auth-strategy.md
2026-01-15-database-choice.md3
Full structure with tooling
1-2 HOURS
Add architecture/, conventions/, and context/ as your project grows. Add frontmatter for structured queries. Connect to tools that maintain freshness.
knowledge/ README.md decisions/ architecture/ conventions/ context/ api/ # Add frontmatter for structured queries: # --- # type: decision # confidence: high # last_validated: 2026-02-01 # ---
Design Principles
Adopt it without changing how your team works.
Git-native
Knowledge lives in the repo, versioned with the code it describes. No external database and no sync problem.
Human-readable first
Markdown files and no proprietary formats. A developer can read and write these without any tooling at all.
AI-consumable
Optional frontmatter gives agents structure to query and reason over, and it is never required.
Tool-agnostic
Tied to no IDE, agent framework, or platform. If a tool reads markdown, it can read knowledge/.
Setup and Onboarding
Turn your codebase into an operating system for autonomous work.
Out of the Box
Intelligent Onboarding
Intelligent onboarding allows teams to get up and running quickly with a knowledge base and day zero value.
Business goals and constraints
Your knowledge base
Specialist lineup and standards
First objectives and review paths
Embedded Applied Team
Codespeed Applied
Our forward deployed engineering team embeds with yours to add hands-on help designing the operating model, rollout strategy, and governance posture.
Operating-model design
Rollout strategy
Governance planning
Career and craft coaching
Instant setup
01
Connect your GitHub organization from your Codespeed account.
02
Create your first project and invite your team to join you.
03
Start onboarding with Lead Dev, and the first session returns work you can review.