KnowKit

Role-based project knowledge base template for humans and AI agents.

中文文档

KnowKit helps teams build an AI-native knowledge memory that a fresh agent can read, route through, and act on without relying on hidden chat history. It turns project context into a structured operating system: roles, routing, verified facts, runbooks, decisions, todos, and private access notes.

Modern AI coding agents are powerful, but they often fail for boring reasons:

• They start without enough project context.
• They mix old memory with current code reality.
• They do not know whether they are acting as an engineer, architect, tester, or product manager.
• They hide uncertainty instead of routing to the right source of truth.
• They scatter secrets, assumptions, and todos across chats.

KnowKit gives agents a predictable entry point and gives humans a maintainable project memory.

• Fresh-agent bootstrap: a clear startup chain from README.md to role selection and task routing.
• Role-based execution: built-in role templates for architect reviewer, engineer, tester, and product manager.
• Intent routing: _meta/search-shortcuts.md maps task intent to the right docs.
• Verified context: docs distinguish current facts, historical context, open questions, and unverified claims.
• Operational memory: runbooks, service maps, decisions, reviews, and todos stay close to the work.
• Private-by-design area: credentials and local-only access data are centralized under private/.
• AI-native maintenance loop: agents can update the knowledge base as they learn new verified facts.

The main template is here:

templates/knowledge-base-template.md

It contains a complete product-independent blueprint, including:

• directory structure
• README.md and INDEX.md templates
• _meta/ governance docs
• role files and role rules
• generic service/domain document template
• todo lifecycle
• private area rules
• git safety guidance

1. Click "Use this template" → "Create a new repository" on this repo's GitHub page.
2. Name it something like my-project-knowledge-base or just knowledge-memory.
3. Clone your new repo into your project workspace:

   cd /path/to/your/workspace
   git clone https://github.com/<you>/my-project-knowledge-base knowledge-memory

cd /path/to/your/workspace
mkdir knowledge-memory
cp /path/to/KnowKit/templates/knowledge-base-template.md knowledge-memory/TEMPLATE.md

Ask Claude Code (or any AI agent) to scaffold it:

Read knowledge-memory/TEMPLATE.md (or knowledge-base-template.md) and generate the
full directory structure from it. Product name: <YOUR_PRODUCT>. Create all files
including README.md, INDEX.md, roles/, _meta/, platform/, services/, runbooks/,
private/, todo/. Leave placeholder content where product-specific facts are needed.

This creates the full directory tree. Then fill in incrementally as you work — you don't need to write everything upfront.

Add this to your project's CLAUDE.md:

## Knowledge Base

Before starting work, read:
1. knowledge-memory/README.md
2. knowledge-memory/INDEX.md
3. knowledge-memory/_meta/search-shortcuts.md
4. knowledge-memory/roles/README.md

Infer the right role from the task. State the active role briefly. Load relevant
domain/service docs before acting. If current code conflicts with the knowledge
base, trust current reality and update the knowledge base.

That's it. Next time you ask Claude Code to work on your project, it will:

1. Read the knowledge base
2. Pick the right role (engineer / architect / tester / PM)
3. Route to relevant docs by intent
4. Work with full project context

You don't need to write everything at once. The knowledge base grows as you work:

knowledge-memory/
  README.md
  INDEX.md
  _meta/
  roles/
  platform/
  backend/
  frontend/
  services/
  runbooks/
  decisions/
  reviews/
  todo/
  private/

KnowKit assumes agents should not all behave the same way.

The role templates are embedded inside templates/knowledge-base-template.md, so one file can generate a complete role-aware knowledge base.

KnowKit treats a knowledge base as an execution router, not an archive.

User task
-> infer role
-> read role rules
-> route by intent
-> load relevant facts
-> verify against current code/live state
-> act
-> update durable knowledge

This keeps AI work grounded, repeatable, and reviewable.

• Do not publish project-specific secrets.
• Do not publish internal company docs unless you have permission.
• Keep real credentials under private/ in your local knowledge base.
• Before making a knowledge base public, export a sanitized copy without private/.
• Current code and live environment data should override stale documentation.

KnowKit currently ships as a Markdown-first template. Future versions may add scaffolding commands, validation scripts, and freshness checks.