12. Tips & Best Practices

Practical advice to get the most out of KaKeKiKoKu. Some are obvious once you know them, but they're not always discovered on their own.

The mindset shift

Work on the knowledge; the output is the compiled result

This is the most important best practice of all. With KaKeKiKoKu, your way of working changes: instead of working directly on the output (code, text, design), you work on creating context and information. The decisions, constraints, intent, discarded alternatives — all of that goes into the knowledge. The final output — the code, the document, the product — is more like a "compiled" version of that knowledge.

It sounds abstract until you experience it. When your AI has the complete knowledge, the output comes out better, faster, and with fewer corrections. Because the AI isn’t guessing — it has the context.

Start with a small project

If it's your first time with KaKeKiKoKu, don't launch it against your largest and most complex project. Start with something new or small. Learn the flow, understand the concepts, and then scale up. The learning curve is short, but it exists.

Work in bounded units

Trust the size caps as discipline, not as walls

KaKeKiKoKu sections cap at 4,000 characters, and every folder sidecar, file sidecar, or entity caps at 52,000 characters of prose. Each resource also stays structurally bounded to 30 top-level sections (including _description) and 60 subsections in total. Relation lines have a budget of their own, so connecting knowledge never costs you writing space. These are not technical limits you fight against — they’re design forces that keep your knowledge usable. Both your AI and you read bounded blocks better than walls of text. Embrace the caps; they pay off fast.

Split early, not when you hit the wall

If a section grows past half its limit, ask yourself whether you’re really writing one topic or two. The same goes for entities pushing past 30,000 characters. A section that wants to be two sections is usually obvious once you look. Split before the cap forces you to.

Hitting the limit is a signal, not a failure

When a section refuses to fit, don’t cram. The section is hiding two sections. Restructure into subsections, or split into two sections, or move part of the content to a separate entity. Almost every time you do this, the result reads better than what you were trying to force into one block.

Talk to your AI about one block at a time

Use the 🤖 button on the specific section you care about, not on the whole resource. The block is the unit of conversation, just as it’s the unit of storage. Your AI focuses on exactly what you asked, and the context you give it stays clean.

About descriptions

The description is the most important field

Of all the fields in a sidecar, _description is the most critical. It's what your AI sees in the index before deciding whether it needs to read the full resource. A good description (concise, precise, 280 characters) is the difference between an AI that knows exactly what everything is and one that has to open files to find out.

Watch descriptions especially closely. If the AI writes a generic or imprecise description, correct it. It's the 10-second investment with the highest return in all of KaKeKiKoKu.

About key sections

Use _summary on folders to orient the AI

When a folder accumulates many files, a new AI doesn't know where to start. A _summary in the folder sidecar gives it the complete picture without needing to read every file. Especially useful in large projects or with multiple work sessions.

Use _conclusions to consolidate results

Finished a research phase, a sprint, or a chapter? Capture the conclusions in _conclusions. It's what the next person (or AI) needs to know — without reading all the detail.

Use _soul to capture the "why"

It's the most valuable section long-term. This is where your thoughts when you made a decision go, why you did it that way, your frustrations, your intent. The code shows the "what" — _soul preserves the "why". Future AIs (and you yourself in three months) will thank you.

Use _whyNot for discarded alternatives

Prevents future sessions from repeating dead ends. If you tried an approach and it didn't work, document it in _whyNot with the reason. The next AI that works on that resource will know that path was already explored and discarded.

About organization

Mark key resources as important

Project rules, architecture decisions, style guides — mark them as important. Your AI will always receive them when opening the project, without you having to ask. It's the way to guarantee that certain knowledge is always present.

Use entities for cross-cutting knowledge

When a decision affects the entire project, don't put it in a specific file's sidecar. Create an entity. Entities are perfect for: architecture decisions, style rules, domain glossaries, strategies, conventions.

Use relationships to connect decisions with implementations

If an architecture decision affects 3 files, link them with relationships. When the AI reads any of them, it will see the connection. This turns your knowledge into a navigable network, not isolated documents.

Describe relationships, not only resources

A relationship without a description is allowed, and it is useful when you are mapping quickly. But the description is where the real knowledge lives: why A points to B, what depends on what, or what the next AI should understand before changing either side. Use the quick arrow gesture to create the link, then complete the description as soon as the reason is clear.

Twelve good relationships beat forty vague ones

Each resource holds up to 12 outgoing relationships within a shared character budget, with descriptions up to 200 characters each. Treat that as a curation tool, not a wall: if a resource keeps asking for more links, it is probably covering more than one topic — split it into smaller connected resources and your AI gets a graph it can actually reason about. The outgoing chip in the path bar shows both dimensions at a glance; spend description characters where the connection genuinely needs explaining.

Move knowledge blocks instead of copying them

When a section or subsection belongs somewhere else, move it. KaKeKiKoKu carries the block, keeps the graph coherent, and adjusts names when needed. Copy-paste is fine when you intentionally duplicate an idea; moving is better when you are refactoring the structure of knowledge.

Don't document everything

Not all files need a sidecar. Decorative images, licenses, standard configuration files — use untracked for them. Documenting for the sake of documenting creates noise and dilutes what's important.

About sharing and publishing

Keep KaKeKiKoKu files out of what you publish

Your .wuniq knowledge is meant to live with your project. Commit it to your repository so your team — and their AIs — get the full context when they clone it. That’s the normal case, and it’s recommended.

Publishing or shipping to end users is the exception. A website, a packaged app, a build artifact — those internal notes shouldn’t travel inside what your users receive. KaKeKiKoKu never mixes into your output on its own; this is about your own packaging step. Use File > Export project for a clean copy with no .wuniq files, or exclude *.wuniq in your build or deploy pipeline (the same way you already exclude bin/ or node_modules/).

About the workflow

Use the 🤖 button instead of explaining

When you want to talk to your AI about something specific, don't type "look at such file, such section" in the chat. Point to it in KaKeKiKoKu and click 🤖. KaKeKiKoKu passes the exact reference. It's faster, more precise, and avoids misunderstandings.

Let the AI document; you review

Don't try to write all sidecars yourself. Tell the AI what you decided, what constraints there are, what you discarded, and let it draft. Review important conceptual changes; the rest, trust.

Sync as a moment of reflection

Get used to seeing sync not just as a detection tool, but as the moment where the AI steps back and thinks about what it did. That's when it detects bugs it overlooked, inconsistencies, loose ends. Don't skip or delay it.

Previous versions before big changes

Make sure the backup system is active. Before restructurings or important changes, ask the AI to "do a labeled backup". If something goes wrong, you can restore.

About search

Use KaKeKiKoKu's search, not the AI's native search

KaKeKiKoKu's search looks inside structured knowledge — descriptions, sections, relationships. It's much more relevant than a file text search. Ask your AI "search in KaKeKiKoKu for..." for any knowledge query.

Start broad enough to discover the right vocabulary, then refine. AI-facing search responses stay within a 30,000-character MCP budget: if a broad result set does not fit, KaKeKiKoKu returns only complete result blocks, explains the omission, and distributes multi-project output fairly. It does not split a result or paginate an oversized answer. A good AI should narrow the expression, add structured filters, or scope the search to one project. The human Web search is separate: it can expose up to 500 results progressively, beginning with 100.

Use a transversal view to compare the same concern

When your AI needs to compare one section — such as _rules, _careful, or a project-specific block — across a folder, ask it to use KaKeKiKoKu's view command. A parent section includes its subsections; a direct PARENT/Child selector focuses on one subsection.

A view is delivered as one logical selection. If every matching body fits in the 30,000-character MCP response budget, the AI receives them all. Otherwise KaKeKiKoKu sends no arbitrary first batch: it replaces the whole selection with a complete resource index and copyable commands for reading each matching block. If max_folder_items stops the scan, KaKeKiKoKu reports the total as a lower bound. The AI should then narrow the folder, remove recursive traversal, or select a concrete subsection.

About the interface

Workspace to open several projects at once

If you always work with the same projects, add them to the workspace list on the welcome screen and leave them checked. Then use Open marked projects to open them together. You can also reorder the list so your AI sees the projects in the order that makes sense for your work.

Organize your projects under a root folder

Work from a root folder with your KaKeKiKoKu projects inside:

MyProjects/
├── ProjectA/
├── ProjectB/
└── ProjectC/

This is not a KaKeKiKoKu requirement — it's how IDEs typically work, due to their permission system. Your AI works better when all projects are accessible from the same base folder. Never place a KaKeKiKoKu project inside another.

Focus mode to concentrate

When you're editing a knowledge resource and want to concentrate without distractions, turn on Focus mode from the display controls in the menu bar. It hides all panels and leaves you with just the editor.

Use the project map before delegating broad work

When you are about to ask the AI for a broad reorganization, open the project map first. It gives you the shape of the project, the important relationship paths, and the blocks that look misplaced. Then ask the AI from a clearer picture instead of describing the whole project from memory.

Use the file viewer to verify, not to replace your editor

Opening source code inside KaKeKiKoKu is useful when you need to check what a file contains while reading its context. Use the quick Markdown/text editor for small project-document changes. For heavy source editing, keep using your normal IDE and let KaKeKiKoKu manage the knowledge around it.