Docs & Best Practices

Set up your workspace for efficient AI-assisted development.

ContextLoom doesn't run Claude or any LLM. It complements AI tools like Claude Code, Cursor, and Windsurf by organizing the files they create on disk.

Recommended workspace setup

A clean workspace structure makes it easy for both you and your AI tools to find, create, and update context files.

1

Keep a single workspace folder

Choose one root directory for your project context. This could be inside your project repo (e.g., `/project/context/`) or a standalone folder. ContextLoom opens this as your workspace.

2

Point your AI tool at the workspace

Configure Claude Code, Cursor, Windsurf, or your preferred agent to read from and write to your workspace directory. Add the ContextDB conventions to your Claude.md, .cursorrules, or project rules file.

3

Create the ContextDB structure

Add the taxonomy folders (00_index through todos) inside a `ContextDB/` subfolder. This gives agents a clear, predictable structure to follow.

4

Add the agent config snippet

Paste the ContextDB conventions snippet into your Claude.md, .cursorrules, or equivalent config file. This tells your AI tool exactly where and how to write files in your workspace.

Best practices

Prefer adding new files over rewriting old ones

When context evolves, create a new file rather than overwriting. This preserves history and lets you track how decisions changed over time.

Link related documents

Use relative Markdown links between files (e.g., a spec linking to its architecture doc). This creates a navigable knowledge graph and reduces duplication.

Keep knowledge summaries separate from raw notes

Write summaries in 04_knowledge/ — never overwrite the source material in other folders. Summaries are compressed views; raw notes are the source of truth.

Use Context Bundles for prompts

Instead of pasting entire folders into a prompt, select only the files relevant to your question. ContextLoom's bundle export makes this one click.

Store and reuse prompts

Keep proven prompts in 05_prompts/ and reference them by path. This makes your prompting repeatable and lets agents follow established patterns.

Review agent output before committing

ContextLoom's preview pane lets you review what an agent wrote before you save or share it. Catch errors early.

Prompt patterns

These patterns work well with ContextDB-organized workspaces. Store them in your 05_prompts/ folder.

Update architecture based on specs

When specs change and architecture docs need to catch up.

Read the spec at 01_specs/[feature].md. Update the architecture doc at 02_architecture/[feature]-arch.md to reflect the current requirements. Preserve existing sections. Add new sections as needed.

Summarize folder into a knowledge doc

When a folder has accumulated many files and you need a quick overview.

Read all files in [folder]. Write a concise summary to 04_knowledge/[folder]-summary.md. Include: key points, decisions made, open items, and links to source files.

Generate TODOs from specs

When starting implementation and you need a clear task list.

Read the spec at 01_specs/[feature].md. Generate a TODO list in todos/[feature]-todos.md with actionable tasks derived from the acceptance criteria.

Create a decision record

When facing a technical or product decision that should be documented.

We need to decide between [Option A] and [Option B] for [topic]. Create an ADR-lite in 03_decisions/ with context, options, pros/cons, and a recommendation.

Build a context bundle

When preparing a focused prompt for another LLM session.

I need to prompt my AI about [topic]. Build a context bundle with the minimum set of files from this workspace that provide relevant context. Output in the Context Bundle format.