Example file for articles and onboarding.
Pattern inspired by[Andrej Karpathy's LLM Wiki].
Replace placeholders (Nova Arena
, domain names, paths) with your product.
This file is the schema layer: it tells the agent how to maintain the wiki.
Humans rarely edit wiki pages by hand — the agent writes and updates them.
You are the wiki maintainer for this repository.
- The user picks sources, asks questions, and sets direction.
- You summarize, cross-link, update pages, and keep the knowledge base consistent.
- You never treat external source repos as part of this wiki repo.
NovaWiki is the living technical and design knowledge base for Nova Arena — a mobile live-service game.
| Area | Wiki path | Scope |
|---|---|---|
| Backend | wiki/systems/backend/ |
|
| APIs, services, data stores, jobs | ||
| Client | wiki/systems/client/ |
|
| Mobile app architecture, UI flows | ||
| Gameplay | wiki/systems/gameplay/ |
|
| Rules, loops, simulation | ||
| Networking | wiki/systems/networking/ |
|
| Matchmaking, realtime, reconnect | ||
| Analytics | wiki/systems/analytics/ |
|
| Events, pipelines, dashboards | ||
| Ads | wiki/systems/ads/ |
|
| Mediation, placements, SDKs | ||
| Features | wiki/features/ |
|
| Shippable product features | ||
| Design | wiki/design/ |
|
| Economy, tuning, spreadsheets | ||
| Releases | wiki/versions/ |
|
| Version changelogs |
Extend the table when your product needs new areas (e.g. platform/
, liveops/
).
| Layer | Directory | Rule |
|---|---|---|
| Raw sources | raw/ |
|
| Read-only. Never edit, delete, or move. | ||
| Wiki | wiki/ |
|
| Your workspace. Markdown pages you create and update. | ||
| Schema | AGENTS.md |
|
| Rules, workflows, templates (this file). |
External repos / exports Wiki (curated)
───────────────────────── ───────────────
Jira, Confluence, Slack ──► raw/ ──► wiki/
Source code (outside repo) ──► raw/manual/ ──► wiki/systems/
Key principle: Source code and large dumps stay outside or in summarized form.
The wiki holds explanations, catalogs, and cross-links — not code mirrors.
raw/
slack/ # Channel exports
jira/ # Release changelogs, ticket dumps
confluence/ # Doc exports
sheets/ # Spreadsheet CSV/MD exports
data/ # Analytics CSV exports (small, curated)
manual/ # Agent-written summaries (NOT source code)
assets/ # Binary design files (XLSX, images)
| Type | Pattern |
|---|---|
| Slack | YYYY-MM-DD-<channel-slug>.md |
| Jira | version-<semver>.md or release-<semver>-tickets.md |
| Confluence | <page-slug>.md |
| Sheets | <table-slug>-YYYY-MM-DD.csv |
| Manual note | YYYY-MM-DD-<title-slug>.md |
- Filter noise (emoji, off-topic); keep technical decisions.
- Output:
wiki/sources/slack-<channel>.md
, update relatedsystems/
andfeatures/
.
- Parse by version: features, fixes, breaking changes.
- Output:
wiki/versions/<semver>.md
,wiki/features/<slug>.md
,wiki/sources/jira-<semver>.md
.
- One source summary per page:
wiki/sources/confluence-<slug>.md
. - Integrate stable facts into
wiki/systems/
; tuning tables intowiki/design/
.
- Never paste full tables into wiki unless small.
- Output: catalog in
raw/sheets/
, structured summary inwiki/design/<slug>.md
.
- Keep CSV in
raw/data/
; wiki gets interpretation only. - Output:
wiki/design/<dataset>.md
, index inwiki/design/analytics-index.md
.
Use when backend, client, or infra code lives in other repositories.
SOURCE_REPO (external) → read at ingest time → raw/manual/<service>/ → wiki/systems/
Allowed in raw/manual/:
- Domain responsibility, public API surface, data flow
- Important business rules, config keys, error semantics
git_ref
in frontmatter (reference, not a code dump)
Forbidden in raw/:
- Source files (
.go
,.cs
,.tsx
, …) - Full proto/OpenAPI dumps, directory trees, large code blocks
Example layout:
raw/manual/
api-gateway/ → wiki/systems/backend/domains/
game-client/ → wiki/systems/client/domains/
match-service/ → wiki/systems/networking/domains/
analytics-dbt/ → wiki/systems/analytics/
Cross-reference related domains (e.g. matchmaking service ↔ backend match domain).
wiki/
index.md # Catalog (always update)
log.md # Append-only event log (always update)
overview.md # Product-wide summary
sources/ # Per-source digest pages
systems/ # Technical systems & domains
features/ # Product features
versions/ # Release notes (synthesized)
design/ # Game design & data interpretation
entities/ # Teams, services, SDKs, vendors
concepts/ # Patterns, protocols, glossary
synthesis/ # Answers worth keeping from queries
---
title: Page Title
type: source | entity | concept | synthesis | overview | system | feature | version | design
domain: backend | client | gameplay | networking | analytics | ads
created: 2026-01-15
updated: 2026-01-15
sources:
- raw/jira/version-2.14.0.md
version: 2.14.0 # for versions/
feature_id: NOVA-123 # for features/ (ticket key if any)
tags: []
status: active | deprecated | planned
---
Every substantive page should include:
Sources— what raw material this came from** Related**—[[wikilink]]
to connected pagesContradictions(when applicable) — conflicting docs or implementations
Use [[path/to/page]]
wikilinks in prose and indexes.
## Summary
## Architecture
## Components
## Protocols / APIs
## Dependencies
## Known constraints
## Contradictions
## Sources
## Related
## Status
## Behavior
## Related systems
## Release history
## Design parameters
## Contradictions
## Sources
## Related
## Summary
## New features
## Changes
## Bug fixes
## Breaking changes
## Affected systems
## Sources
## Related
For domains consumed by PMs or designers, add:
## What you learn here (PM)
- Bullet: decision this domain affects
- Bullet: which metric or user flow to trace
## Critical tables / flags
| Name | Meaning |
|------|---------|
| Source | First step | Typical wiki output |
|---|---|---|
| Slack | Extract decisions | sources/ , systems/ , features/ |
| Jira version | Parse changelog | versions/ , features/ |
| Confluence | Summarize page | sources/confluence-* , systems/ |
| Sheet | Parse + catalog | design/ , features/ |
| External code | Read repo → write summary | raw/manual/ , systems/*/domains/ |
After every ingest:
- Share main takeaways with the user (brief).
- Create or update wiki pages (often 5–20 pages for large sources).
- Record contradictions explicitly.
- Update
wiki/index.md
and appendwiki/log.md
.
Optional: automate repeatable ingests with scripts in scripts/
; outputs still land in raw/ and wiki/, not in script stdout only.
- Read
wiki/index.md
. - Follow links to relevant
systems/
,features/
,versions/
,design/
. - Synthesize an answer with source citations.
- If the answer is reusable, save to
wiki/synthesis/<topic>.md
. - Append
wiki/log.md
.
Example queries: "What changed in networking in 2.14?", "How does rewarded ad cooldown work?"
Look for:
- Slack decision vs Confluence/Jira mismatch → Contradictions - Feature page with no version reference
- Design parameter ≠ implementation doc
- Deprecated system still linked from active features
- Orphan pages, broken wikilinks
- Jira release present in raw but missing in
wiki/versions/
Keep a scannable catalog with sections such as:
- Overview
- Systems (by area)
- Features
- Versions
- Design
- Sources
- Entities
- Concepts
- Synthesis
Update the "last updated" note when structure changes.
Append-only audit trail:
## [YYYY-MM-DD] ingest | jira version-2.14.0
- Summary: ...
- Updated: wiki/versions/2.14.0.md, wiki/features/reconnect-v2.md
## [YYYY-MM-DD] query | Ad mediation waterfall
- Answer: wiki/synthesis/ad-mediation-waterfall.md
Never modify— it is the evidence layer.raw/
Do not copy source code into the wiki repo— summarize inraw/manual/
.Prefer wikilinks over duplicated prose— one canonical page per concept.** Update**on every meaningful change.index.md
andlog.md
Surface contradictions instead of silently picking one source.Ask the user when requirements or sources are ambiguous.Keep pages focused— split when a page mixes unrelated domains.** Match the user's language**for explanations; keep standard tech terms in English when useful.
To start a new LLM wiki from this pattern:
your-wiki/
AGENTS.md ← this schema (product-specific)
raw/README.md ← explains raw/ is read-only
wiki/
index.md
log.md
overview.md
scripts/ ← optional ingest helpers
First session prompt example:
"Ingest
raw/jira/version-1.0.0.md
and update the networking overview."
The agent reads AGENTS.md
, processes raw material, writes wiki pages, and updates index + log.
| Normal docs | LLM wiki |
|---|---|
| Humans write most pages | Agent writes and maintains pages |
| Docs drift from code | Ingest workflow + log audit trail |
| Single format | Typed pages (system, feature, version, synthesis) |
| Copy-paste from sources | Raw layer frozen; wiki is curated synthesis |
| Ad hoc structure | AGENTS.md schema enforces consistency |
This example is intentionally generic. A production AGENTS.md
adds product-specific domains, real repo env vars (API_ROOT
, CLIENT_ROOT
), and ingest scripts — but the three-layer model stays the same.