Skip to content

ide-integration.md

Latest commit

 

History

History
102 lines (69 loc) · 5.39 KB

ide-integration.md

File metadata and controls

102 lines (69 loc) · 5.39 KB
Raw

Export the guidance to other AI assistants

This repository is packaged as an OpenCode skill, but the guidance in SKILL.md is portable. scripts/export_rules.py writes it to the rule-file path each assistant reads, with the frontmatter that tool needs.

Before you start

Read Context cost first. Eight of the eleven default targets load into every request in the project. The optional legacy Cursor target brings the total to nine always-on targets.

List the targets

python scripts/export_rules.py --list

12 rule-file targets across 11 assistants (11 selected by default):

Key Tool Path Default Always-on
cursor Cursor .cursor/rules/diataxis.mdc yes no
cursor-legacy Cursor (legacy) .cursorrules no yes
cline Cline .clinerules/diataxis.md yes yes
roo Roo Code .roo/rules/diataxis.md yes yes
windsurf Windsurf .windsurf/rules/diataxis.md yes no
copilot GitHub Copilot .github/copilot-instructions.md yes yes
claude Claude Code CLAUDE.md yes yes
codex OpenAI Codex AGENTS.md yes yes
aider Aider CONVENTIONS.md yes yes
gemini Gemini CLI GEMINI.md yes yes
continue Continue .continue/rules/diataxis.md yes no
amazonq Amazon Q Developer .amazonq/rules/diataxis.md yes yes

Preview before writing

--dry-run reports what would happen and writes nothing:

python /path/to/diataxis-docs-skill/scripts/export_rules.py --target . --dry-run

Export

Run from the project that should receive the rule files, or point --target at it:

# Everything, into the current project. Windsurf automatically uses compact
# output when the full guide would exceed its platform limit.
python /path/to/diataxis-docs-skill/scripts/export_rules.py

# Only the tools your team uses, compact form
python /path/to/diataxis-docs-skill/scripts/export_rules.py --only claude --only cursor --compact

Existing files are never overwritten unless you pass --force.

Options

Option Effect
--target DIR Project to export into. Defaults to the current directory.
--only KEY Export one target. Repeat for several.
--list Print the target table and exit.
--dry-run Report planned writes without touching the filesystem.
--force Overwrite existing rule files.
--compact Export five sections instead of the whole guide.

Context cost

An always-on rule file is prepended to every request in that project. The full guidance is about 20,900 characters, roughly 5,200 tokens per request.

--compact exports only the compass, the quick decision tree, the non-trigger list, the anti-patterns, and the quality checks — about 9,400 characters, roughly 2,300 tokens. That is enough for the assistant to classify a request correctly and to avoid the common failure modes.

Eight of the eleven default targets are always-on; the legacy Cursor target is optional and makes nine always-on targets when selected. Use the full export for the targets that load conditionally (cursor, windsurf, continue), keeping in mind that Windsurf automatically receives compact output when full output is over its limit. Use --compact for the rest.

Tool-specific notes

Cursor. Project rules must use the .mdc extension; a plain .md file in .cursor/rules is ignored by the rules system. The script writes .cursor/rules/diataxis.mdc with description and alwaysApply: false, which makes it an agent-requested rule: Cursor reads the description and pulls the rule in when the task looks documentation-related. The modern target is selected by default. Use --only cursor-legacy only for an older Cursor setup, and never select both targets together.

Cline. Workspace rules live in the .clinerules/ directory. The exporter writes .clinerules/diataxis.md; a single .clinerules file is not the current directory-based format.

Windsurf. Workspace rules are capped at 12,000 characters per file. The full guidance exceeds that, so the exporter automatically falls back to the compact guide for this target; pass --compact when you want every target to use the same compact source. The legacy .windsurfrules target is not offered: its 6,000-character limit is smaller than even the compact guide, so it has no valid export mode. Delete a stale .windsurfrules generated by an earlier version.

Roo Code. Every file in .roo/rules/ is loaded on every request, so this target is effectively always-on even though it lives in a rules directory.

Continue. The script writes name, description, and alwaysApply: false, which lets the agent decide when to pull the rule in.

Aider. Writing CONVENTIONS.md is only half the job. Aider does not read it until you add it to .aider.conf.yml:

read:
  - CONVENTIONS.md

Keep exports out of version control

The exported files are derived from SKILL.md. This repository's .gitignore excludes them so a local export never lands in a commit. In your own project, decide whether to commit them: committing shares the rules with your team, and ignoring them keeps a single source of truth.

Re-export after an update

git -C /path/to/diataxis-docs-skill pull
python /path/to/diataxis-docs-skill/scripts/export_rules.py --target . --force