Claude Code Integration

Claude Code is Anthropic's official CLI tool for AI-assisted development. Oidis projects can include configuration files that give Claude deep knowledge of the framework architecture, coding conventions, and project-specific patterns.

File Structure

Claude Code uses the following files in each project:

File	Purpose	In Git?
CLAUDE.md	Project-specific instructions (architecture, conventions, patterns)	Yes
.claude/settings.json	Shared project settings (permissions, MCP servers)	Optional
.claude/settings.local.json	Personal local settings (user-specific permissions)	No
~/.claude/CLAUDE.md	Global instructions applied to all projects	N/A (user home)

CLAUDE.md

The CLAUDE.md file at the project root is the primary way to give Claude context about the project. It is loaded automatically when Claude Code is started in the project directory.

What to include:

• Project overview and business domain
• Architecture patterns and directory structure
• Strict rules (no commits, no DB operations, no builds without permission)
• Import conventions and key framework APIs
• Business entities and their relationships

Copyright header — use HTML comment format (same as .mdx files):

<!--
Copyright {YEAR} Oidis

SPDX-License-Identifier: BSD-3-Clause
The BSD-3-Clause license for this file can be found in the LICENSE.txt file included with this distribution
or at https://spdx.org/licenses/BSD-3-Clause.html#licenseText
-->

# Project Name - Claude Code Instructions
...

.claude/settings.local.json

This file contains personal permission settings (which tools Claude can use without asking). It is generated automatically by Claude Code as you approve tool usage.

Never commit this file

settings.local.json contains user-specific permissions and paths. Always add it to .gitignore.

.gitignore

Oidis Builder auto-generates most of the .gitignore file. Only the "Project individual ignore patterns" section at the bottom of the file is preserved across builder runs. All custom ignore rules — including Claude Code files — must be placed in this section:

# Project individual ignore patterns
...
.claude/settings.local.json

warning

Do not add ignore rules above the "Project individual ignore patterns" section — Oidis Builder will overwrite them on the next build task.

Global Configuration

The global ~/.claude/CLAUDE.md file contains rules that apply to all Oidis projects. Each developer maintains their own copy in ~/.claude/CLAUDE.md.

What to Include in Global CLAUDE.md

• Implicit Oidis context — when you say "wiki", "builder", "commons", "gui", "hub", etc., Claude should understand these refer to Oidis CORE packages and their wiki documentation, not search the filesystem speculatively
• Information lookup priority — (1) Oidis Wiki content first, (2) filesystem/source as fallback, (3) external sources last
• Wiki topic table — maps topic keywords to wiki directory paths for fast lookup
• Code formatting and linting rules — spacing, naming, member ordering
• File header / copyright requirements — year format, license template
• Dependency and licensing policies — BSD-3-Clause compatibility
• Security and execution safety — no production scripts, no destructive DB ops without confirmation
• Git and VCS policies — commit format, no --no-verify, no auto-push

Recommended Global Rules

## Implicit Oidis Context (HIGH PRIORITY)

When the user says just "wiki", they always mean Oidis Wiki (`io-oidis-wiki`).
Bare names like "builder", "commons", "gui", "hub" always refer to the
corresponding Oidis CORE package and their wiki documentation.
If unsure, ask rather than searching the filesystem speculatively.

**Information lookup priority:**
1. Oidis Wiki content (`source/markdown/`) — check it first
2. Filesystem / source code — only as fallback
3. External sources — last resort

Topic Table

Add a topic-to-path mapping so Claude can quickly find the right wiki section:

| Topic | Wiki path |
|-------|-----------|
| Architecture & patterns | `05-Architecture/` |
| Models & DB | `06-Models/` |
| GUI (panels, controllers, tables, dialogs) | `07-GUI/` |
| Decorators (@Entity, @Extern, @Route, ...) | `08-Decorators/` |
| Utility API (LogIt, StringUtils, ...) | `09-Utilities/` |
| Conventions (naming, formatting) | `10-Conventions/` |
| Configuration (JSONP, commons, solutions) | `11-Configuration/` |
| Advanced (Docker, testing, ForceCompile) | `12-Advanced/` |
| Builder (CLI, tasks, config, deploy) | `13-Builder/` |
| Getting Started | `02-Getting Started/` |
| Guides (IDE, coding standards, VCS) | `03-Guides/` |

Individual projects inherit these global rules and add project-specific context in their own CLAUDE.md.

Setting Up a New Project

1. Create CLAUDE.md at the project root with the HTML comment copyright header
2. Add .claude/settings.local.json to .gitignore
3. Reference global rules at the top of your CLAUDE.md:

   > **Global rules** (formatting, linting, framework concepts, licensing) → `~/.claude/CLAUDE.md`

4. Document project specifics — architecture, directory structure, business entities, strict rules

Framework Knowledge

Point Claude to the local clone of this wiki repository for deep framework knowledge. Add this to your global ~/.claude/CLAUDE.md:

Full framework documentation lives in the `io-oidis-wiki` repository.
Local clone: `D:\__PROJECTS__\Oidis\Source\io-oidis-wiki\source\markdown\`

Claude will read the relevant wiki sections before generating code when unsure about architecture or patterns.

Review System

The Oidis Review System is a three-layer quality gate that catches convention violations before they get committed. It uses Claude Code Skills and Hooks to enforce all documented rules automatically.

Architecture

Layer 1: HOOKS (proactive)       — Block forbidden patterns (Co-Authored-By, --no-verify, npm/npx)
Layer 2: SKILL /review           — On-demand validation against rule reference files
Layer 3: SKILL /review-wiki      — Wiki-specific MDX and governance rules
Layer 4: SKILL /sync-dependency  — Cross-repository dependency synchronization

Distribution

The review system ships as a Claude Code plugin (oidis) from a dedicated marketplace repository (io-oidis-claude). The plugin is the single source of truth — skills, hooks, the conventions guide, and Builder command shortcuts are versioned together and installed natively through /plugin, replacing the previous shell-script install approach.

Component	Provided by the plugin
/oidis:review	Code review against Oidis conventions
/oidis:review-wiki	Wiki MDX and governance review
/oidis:sync-dependency	Cross-repo dependency synchronization
oidis-conventions	Always-on authoring rules the linter does not enforce
PreToolUse hooks	Block Co-Authored-By, --no-verify, --no-gpg-sign, and npm/npx in Oidis projects

tip

To change a skill or rule, edit it in the plugin repo and bump the plugin version — never edit the installed copy under the plugin cache, it is overwritten on update.

Installation

Add the Oidis marketplace and install the plugin:

/plugin marketplace add https://gitlab.com/oidis/io-oidis-claude.git
/plugin install oidis@oidis

A solution project can also declare the marketplace and plugin in its committed .claude/settings.json (extraKnownMarketplaces + enabledPlugins), so the plugin installs automatically the first time a developer opens the project — ideal for onboarding clients and new team members.

Usage

# Review staged changes (default)
/review

# Review all changes including unstaged
/review --all

# Review a specific file
/review path/to/file.ts

# Wiki-specific review
/review-wiki

# Sync dependency changes to standalone clone
/sync-dependency io-oidis-hub-gui

# Reverse sync: standalone clone → dependencies/
/sync-dependency io-oidis-commons --reverse

The review produces a structured report with three severity levels:

Severity	Meaning	Action
BLOCK	Hard rule violation (missing copyright, console.*, wrong quotes)	Must fix before commit
WARNING	Convention issue (missing JSDoc, spacing, naming)	Should fix
INFO	Suggestion (missing description, naming improvement)	Consider

Rule Reference Files

Rules are stored as plain markdown files in the skill's references/ directory. Each file covers a specific topic:

File	Skill	Covers
rules-git.md	/review	Commit format, branch naming, staging
rules-typescript.md	/review	Formatting ( : Type, quotes, semicolons, compactness, LogIt)
rules-naming.md	/review	PascalCase/camelCase, $ params, getters/setters, enums
rules-copyright.md	/review	Headers, year rules, license compatibility
rules-jsdoc.md	/review	Approved tags, format, when required
rules-gui.md	/review	Framework OOP vs vanilla DOM, forbidden patterns
rules-testing.md	/review	When/how to run unit tests, E2E tests, forbidden commands
rules-mdx-format.md	/review-wiki	MDX extension, frontmatter, cross-references
rules-wiki-governance.md	/review-wiki	See also, overview updates, orphans
rules-wiki-content.md	/review-wiki	English content, admonitions, code examples

Extending Rules

To add or update a rule:

1. Edit the appropriate rules-*.md file in the plugin repo (io-oidis-claude/skills/{skill-name}/references/)
2. Bump version in .claude-plugin/plugin.json and push
3. Developers pick it up via /plugin marketplace update oidis (or automatically with autoUpdate: true)

To add a new rule category:

1. Create rules-{category}.md in the skill's references/ directory in the plugin repo
2. Update the skill's SKILL.md to reference the new file
3. Bump the plugin version and push

Hooks (Proactive Prevention)

Global hooks run on every Bash tool call across all projects. They block:

• Co-Authored-By in any git commit command
• --no-verify on any git command
• --no-gpg-sign on any git command

The hook scripts ship with the plugin and use only bash builtins and grep/sed — no jq dependency (works on Windows Git Bash).

Updating

Update to the latest published plugin version:

/plugin marketplace update oidis

Maintainers bump version in the plugin's .claude-plugin/plugin.json per release; set autoUpdate: true on the marketplace entry to update on startup automatically.

Best Practices

• Keep CLAUDE.md concise — focus on what Claude needs to generate correct code, not exhaustive documentation
• Use strict rules to prevent dangerous operations (commits, DB changes, production scripts)
• Reference the wiki instead of duplicating framework docs in CLAUDE.md
• Update CLAUDE.md when project architecture evolves (new entities, new patterns, new conventions)
• Review permissions in .claude/settings.local.json periodically — remove overly broad patterns
• Run /review before committing — it catches convention violations that Claude may introduce due to context limitations

---

See also: IDE Configuration | Version Control | Coding Standards