assets/claude-rule-template.md
# Claude Code Rule — Starter Templates
Templates for Claude Code project instructions and scoped rules.
---
## Project instructions (`CLAUDE.md` or `.claude/CLAUDE.md`)
No frontmatter needed. Write plain markdown. Target under 200 lines.
```markdown
# Project Instructions
## Language and runtime
-
## Code style
-
## Architecture
-
## Testing
-
## Error handling
-
## Build and run
-
## Security
-
```
You can import additional files using `@path` syntax:
```markdown
See @README.md for project overview and @package.json for available scripts.
# Additional Instructions
- Git workflow: @docs/git-instructions.md
```
---
## Path-scoped rule (`.claude/rules/<name>.md`)
```markdown
---
paths:
- "<glob-pattern>"
---
# <Rule title>
-
-
-
```
Multiple patterns and brace expansion are supported:
```markdown
---
paths:
- "src/**/*.{ts,tsx}"
- "lib/**/*.ts"
---
# <Rule title>
-
-
-
```
---
## Unconditional rule (`.claude/rules/<name>.md`)
Omit `paths` to make the rule load every session:
```markdown
# <Rule title>
-
-
-
```
assets/copilot-instructions-template.md
# Copilot Instructions — Starter Template
Use this as the starting structure for `.github/copilot-instructions.md`.
Delete sections that do not apply. Keep directives concise and imperative.
---
```markdown
# Copilot Instructions
## Language and runtime
-
## Code style
-
## Architecture
-
## Testing
-
## Error handling
-
## Documentation
-
## Git conventions
-
## Security
-
```
assets/creation-follow-up.md
# Rule creation follow-up questions
Questions to ask per rule when the scan and initial interview leave gaps. Ask only what's missing — skip anything already answered.
---
## Purpose and scope
> "What problem does this rule solve? What would go wrong without it?"
Ensures the rule has a reason to exist. If the developer can't explain the problem, the rule may not be needed.
> "Is this a hard requirement or a preference?"
Hard requirements become imperative directives ("Use X"). Preferences become softer guidance ("Prefer X over Y when Z").
---
## Specificity
> "Can you give a concrete example of code that follows this rule and code that violates it?"
Turns vague conventions into testable directives. If the developer can't give an example, the rule is too abstract.
> "Does this apply to new code only, or should existing code be refactored to match?"
Determines whether the rule is forward-looking or retroactive. Forward-only: "For new files, use X." Retroactive: "Use X."
---
## Exceptions
> "Are there cases where this rule should NOT apply?"
Common exception patterns:
- Generated code / vendor files
- Test code vs production code
- Legacy modules being phased out
- Third-party API boundaries (must match external conventions)
- Performance-critical paths with different patterns
> "If there are exceptions, how should the AI recognize them?"
Options: file path (`tests/`, `generated/`), filename pattern (`*.generated.ts`), comment marker (`// legacy`), or directory convention.
---
## Boundaries
> "Does this rule interact with or depend on other rules?"
Catches conflicts early. Example: "Use named exports" + "Re-export everything from index.ts" — the AI needs to know both.
> "Should this rule override the linter/formatter, or defer to it?"
If a tool already enforces it (ESLint, Biome, Ruff), the rule may be redundant. Best to reference the tool instead of duplicating.
---
## Granularity
> "Does this apply everywhere, or only to specific directories/file types?"
Determines always-on vs scoped. See `assets/frontmatter-scenarios.md` for frontmatter options.
> "Should this be one rule or split into several?"
Split when: different parts apply to different paths, or the rule covers unrelated concerns.
Keep together when: the parts are meaningless in isolation.
---
## Voice and format
> "How strict should the directive be?"
| Level | Phrasing | Use when |
|-------|----------|----------|
| Required | "Always use X." / "Never do Y." | CI enforces it or team agrees it's non-negotiable |
| Preferred | "Prefer X over Y." | Convention, but exceptions exist |
| Conditional | "When doing Z, use X." | Only applies in specific contexts |
> "Anything the AI should explicitly avoid doing, even if it seems reasonable?"
Captures anti-patterns the developer has seen the AI produce. Example: "Do not add `any` type assertions even if it fixes a type error."
---
## Validation
> "How would you verify the AI followed this rule?"
If it's testable (linter, type check, test suite), mention the command. If it's a judgment call (architecture, naming), note that.
> "Is there an existing doc or ADR that backs this up?"
Claude Code can import it with `@path`. Copilot and Cursor need the content inlined.
---
## Usage guide
Use these questions during **Step 3 (Interview)** for each convention discovered in the scan. Don't ask all questions for every rule — pick the ones where context is missing:
| Signal | Questions to ask |
|--------|-----------------|
| Scan found a convention but no rationale | Purpose and scope |
| Convention seems broad / vague | Specificity |
| Convention might conflict with test or legacy code | Exceptions |
| Multiple related conventions found | Boundaries, Granularity |
| Developer gave a preference without strength | Voice and format |
| No obvious way to verify | Validation |
assets/cursor-rule-template.mdc
# Cursor Rule — Starter Template
Use this as the starting structure for `.cursor/rules/<name>.mdc`.
Set frontmatter fields to control activation mode, then add concise, imperative directives.
---
## Always-apply rule
```markdown
---
alwaysApply: true
---
-
-
-
```
## Glob-scoped rule (activates when matching files are in context)
```markdown
---
description: "<what this rule covers>"
globs: "<glob-pattern>"
alwaysApply: false
---
-
-
-
```
## Agent-selected rule (Agent decides relevance from description)
```markdown
---
description: "<what this rule covers — be specific for good matching>"
alwaysApply: false
---
-
-
-
```
## Manual rule (only applied when @-mentioned in chat)
```markdown
---
---
-
-
-
```
assets/frontmatter-scenarios.md
# Frontmatter scenarios
Decision tree for choosing the right frontmatter. Each scenario includes what to ask when context is missing.
---
## 1. Does this convention apply everywhere or only to certain files?
**Ask when:** The scan found a convention but it's unclear whether it's universal or path-specific.
> "Does this apply to all code in the repo, or only to specific directories/file types?"
**If everywhere** → always-on (Scenario 2)
**If specific paths** → path-scoped (Scenario 3)
**If unclear** → "Can you give an example of a file where this matters and one where it doesn't?"
---
## 2. Always-on rules
The convention applies to all files — code style, naming, error handling, commit format.
**GitHub Copilot** — root instructions (no frontmatter):
```
.github/copilot-instructions.md
```
**Cursor** — `alwaysApply: true`:
```yaml
---
alwaysApply: true
---
```
**Claude Code** — `CLAUDE.md` or rule without `paths`:
```
CLAUDE.md
.claude/rules/code-style.md # no paths = unconditional
```
---
## 3. Path-scoped rules
The convention applies only to specific directories or file types.
**Ask when:** The developer says "this is only for the API" but hasn't named the exact directory.
> "Which directory or file pattern should trigger this rule? (e.g., `src/api/**`, `**/*.test.ts`)"
**Ask when:** Multiple directories might match.
> "Should this cover just `src/api/` or also `src/middleware/` and `src/validators/`?"
**GitHub Copilot** — `applyTo`:
```yaml
---
applyTo: "src/api/**"
---
```
**Cursor** — `globs`:
```yaml
---
globs: "src/api/**"
alwaysApply: false
---
```
**Claude Code** — `paths`:
```yaml
---
paths:
- "src/api/**"
---
```
### Multiple patterns
When one rule covers several file types or directories:
```yaml
# Copilot
applyTo: "**/*.{ts,tsx}"
# Cursor
globs:
- "**/*.ts"
- "**/*.tsx"
# Claude Code
paths:
- "**/*.{ts,tsx}"
- "lib/**/*.ts"
```
---
## 4. Who should use this rule — coding agent, code review, or both?
**Ask when (Copilot only):** The convention might not apply to code review (e.g., "generate tests" makes sense for coding but not review).
> "Should this instruction apply to both Copilot coding and code review, or just one?"
**If both** → omit `excludeAgent`
**If coding only:**
```yaml
---
applyTo: "**/*.ts"
excludeAgent: "code-review"
---
```
**If review only:**
```yaml
---
applyTo: "**/*.ts"
excludeAgent: "coding-agent"
---
```
No equivalent in Cursor or Claude Code.
---
## 5. Should an AI agent use this rule automatically, or only when relevant?
**Ask when (Cursor only):** The rule is topical (architecture, deployment) rather than file-specific.
> "Should this rule always be active, or should the agent include it only when the topic comes up?"
**If always** → `alwaysApply: true` (Scenario 2)
**If topic-dependent:**
```yaml
---
description: "Conventions for database migrations and schema changes"
alwaysApply: false
---
```
**If rarely needed / reference-only:**
> "Is this something developers would explicitly ask for, or should it auto-activate?"
**If explicit only** → manual (no `alwaysApply`, no `globs`, no `description` — @-mention to activate)
---
## 6. Does the repo already have docs that cover this?
**Ask when (Claude Code only):** The scan found `CONTRIBUTING.md`, ADRs, or other docs that overlap with what the developer wants in rules.
> "I found existing docs that cover this. Should we import them into CLAUDE.md instead of duplicating the content?"
**If yes** → use `@path` imports:
```markdown
See @CONTRIBUTING.md for code style and PR conventions.
See @docs/architecture.md for system design decisions.
```
No equivalent in Copilot or Cursor — content must be written directly.
---
## 7. Does a subfolder have its own conventions?
**Ask when:** The repo is a monorepo or has directories with distinct tech stacks / patterns.
> "Does `packages/ui/` follow different conventions than the rest of the repo?"
**If yes:**
```yaml
# Copilot — scoped instruction
applyTo: "packages/ui/**"
# Cursor — subdirectory in .cursor/rules/
.cursor/rules/ui/components.mdc
# Claude Code — subdirectory CLAUDE.md
packages/ui/CLAUDE.md
```
---
## 8. Is root instructions getting too long?
**Ask when:** The drafted root file exceeds ~80 lines (Copilot), ~500 lines (Cursor), or ~200 lines (Claude Code CLAUDE.md).
> "The root instructions are at [X] lines. Can we move any of these conventions into scoped rules for specific directories?"
Look for conventions that only matter for certain file types and split them out.
---
## Quick reference
| Field | Editor | Purpose |
|-------|--------|---------|
| `applyTo` | Copilot | Glob — when matching files are open |
| `excludeAgent` | Copilot | Skip coding agent or code review |
| `globs` | Cursor | Glob — when matching files are in context |
| `alwaysApply` | Cursor | `true` = every session |
| `description` | Cursor | Agent reads this to decide relevance |
| `paths` | Claude Code | Glob — when matching files are read |
| `@path` | Claude Code | Import file content into CLAUDE.md |
## Glob cheat sheet
| Pattern | Matches |
|---------|---------|
| `src/**/*.ts` | All `.ts` files under `src/` recursively |
| `**/*.test.ts` | All test files anywhere |
| `src/api/**` | Everything under `src/api/` |
| `*.md` | Markdown files in root only |
| `**/*.md` | All markdown files everywhere |
| `**/*.{ts,tsx}` | TypeScript and TSX files |
| `src/{components,hooks}/**` | Multiple directories |
### Common mistakes
| Mistake | Fix |
|---------|-----|
| `**/*` as a glob scope | Use always-on (root file / `alwaysApply` / no `paths`) |
| `*.ts` (no `**`) | Use `**/*.ts` to match nested files |
| `src/api` (no trailing `/**`) | Use `src/api/**` for directory contents |
assets/quality-checklist.md
# Quality checklist for AI coding rules
Review every rule file against this checklist before finalizing.
## Root instructions (`copilot-instructions.md`)
- [ ] **Conciseness** — Under ~80 lines. Every line is an actionable directive.
- [ ] **Imperative voice** — Uses "Use X", "Do Y", not "You should consider X".
- [ ] **No explanations** — Directives only, not rationale. Copilot needs rules, not reasons.
- [ ] **No secrets** — No API keys, passwords, connection strings, or environment-specific values.
- [ ] **No duplication** — Nothing repeated in scoped instruction files.
- [ ] **Covers key areas** — Language, style, architecture, testing, error handling as applicable.
- [ ] **Accurate** — Every convention matches what the team actually follows.
## Scoped instructions (`.github/instructions/*.instructions.md`)
- [ ] **Valid frontmatter** — Has `applyTo` field. Optionally `excludeAgent` to scope to a specific agent.
- [ ] **Correct glob** — Pattern matches intended files (verified against actual repo paths).
- [ ] **Not too broad** — Glob is not `**/*` or equivalent (use root instructions instead).
- [ ] **Conciseness** — Under ~50 lines per file. Split if larger.
- [ ] **No overlap** — Does not repeat guidance from root instructions.
- [ ] **Kebab-case filename** — Named `<domain>.instructions.md`.
- [ ] **Scoped content** — Every directive is specific to the matched files.
## Cursor rules (`.cursor/rules/*.mdc`)
- [ ] **Valid frontmatter** — Uses correct combination of `description`, `globs`, and `alwaysApply` for the intended activation mode.
- [ ] **Correct globs** — Pattern matches intended files (verified against actual repo paths).
- [ ] **Not too broad** — Glob-scoped rules do not use `**/*` (use `alwaysApply: true` instead).
- [ ] **Conciseness** — Under ~500 lines per file. Split if larger.
- [ ] **No overlap** — Does not repeat guidance from always-apply rules.
- [ ] **Kebab-case filename** — Named `<domain>.mdc`.
- [ ] **Scoped content** — Every directive is specific to the matched files.
- [ ] **Description quality** — Agent-selected rules have a clear, specific description for relevance matching.
## Claude Code (`CLAUDE.md` and `.claude/rules/*.md`)
- [ ] **Conciseness** — `CLAUDE.md` under ~200 lines. Longer files reduce adherence.
- [ ] **Imperative voice** — Specific, verifiable directives.
- [ ] **No secrets** — No API keys, passwords, connection strings, or environment-specific values.
- [ ] **No duplication** — Nothing repeated between `CLAUDE.md` and `.claude/rules/` files.
- [ ] **Valid frontmatter** — Scoped rules have `paths` with correct glob patterns. Rules without `paths` are intentionally unconditional.
- [ ] **Correct paths** — Glob patterns match intended files (verified against actual repo paths).
- [ ] **Kebab-case filename** — Named `<domain>.md`.
- [ ] **One topic per file** — Each rule file covers a single domain.
- [ ] **Import hygiene** — `@path` imports in CLAUDE.md point to files that exist.
## Common pitfalls
- [ ] **Vague directives** — "Write clean code" → Replace with specific rules.
- [ ] **Wall of text** — Paragraph-style prose → Convert to bullet-point directives.
- [ ] **Aspirational rules** — Rules the team doesn't actually follow → Remove or mark as goals.
- [ ] **Overly narrow glob** — `src/components/Button.tsx` → Broaden to `src/components/**/*.tsx`.
- [ ] **Missing context** — References internal terms without definition → Add brief clarification.
assets/scoped-rule-template.md
# Scoped Rule — Starter Templates
Templates for path-specific rules. Choose the format matching your editor.
---
## GitHub Copilot (`.github/instructions/<name>.instructions.md`)
```markdown
---
applyTo: "<glob-pattern>"
---
-
-
-
```
Optional: add `excludeAgent: "code-review"` or `excludeAgent: "coding-agent"` to limit which Copilot agent uses the file.
---
## Cursor (`.cursor/rules/<name>.mdc`)
See `assets/cursor-rule-template.mdc` for the full starter template.
```markdown
---
description: "<what this rule covers>"
globs: "<glob-pattern>"
alwaysApply: false
---
-
-
-
```
---
## Claude Code (`.claude/rules/<name>.md`)
See `assets/claude-rule-template.md` for the full starter template.
```markdown
---
paths:
- "<glob-pattern>"
---
# <Rule title>
-
-
-
```
Omit the `paths` frontmatter to make the rule load unconditionally (every session).
CHANGELOG.md
# Changelog
## 0.1.1 - 2026-05-07
### patch
- [#170](https://github.com/equinor/fusion-skills/pull/170) [`5e43223`](https://github.com/equinor/fusion-skills/commit/5e432232917b2b1642431d80cf1698bbefe80ee8) - Apply caveman-compress prose style to SKILL.md.
- Drop articles, filler, hedging from SKILL.md activation body
## 0.1.0 - 2026-03-21
### minor
- [#116](https://github.com/equinor/fusion-skills/pull/116) [`2037597`](https://github.com/equinor/fusion-skills/commit/20375978cba700b828b5c912e7159ef117ee2422) - Add fusion-rule-author support skill with workflow, templates, and references
Internal support skill providing the canonical 7-step authoring workflow, starter templates, frontmatter scenarios, follow-up questions, quality checklist, and tech-stack examples for GitHub Copilot, Cursor, and Claude Code rule files.
references/examples.md
# Examples of well-written AI coding rules
Concrete examples across different tech stacks, showing good patterns and common anti-patterns for GitHub Copilot, Cursor, and Claude Code.
---
## Example 1 — TypeScript / React monorepo
### Root instructions (`copilot-instructions.md`)
```markdown
# Copilot Instructions
## Language and runtime
- Use TypeScript strict mode for all source files.
- Target ES2022. Do not use legacy patterns (var, arguments object).
- Use Bun as the package manager and test runner.
## Code style
- Use named exports, not default exports.
- Prefer `interface` over `type` for object shapes.
- Use `camelCase` for variables and functions, `PascalCase` for types and components.
- Keep files under 300 lines. Extract when larger.
## React conventions
- Use functional components with hooks exclusively.
- Co-locate component, styles, and tests in the same directory.
- Prefer composition over prop drilling; use context sparingly.
## Testing
- Write tests with Vitest. Place test files next to source as `*.test.ts(x)`.
- Test behavior, not implementation. Avoid mocking internals.
- Every bug fix must include a regression test.
## Error handling
- Use Result types for expected failures. Reserve exceptions for unexpected errors.
- Never swallow errors silently. Log or propagate.
```
### Scoped instruction (`instructions/api-routes.instructions.md`)
```markdown
---
applyTo: "src/api/**"
---
- Use Hono framework patterns for route handlers.
- Validate request bodies with Zod schemas before processing.
- Return consistent error shapes: `{ error: string, code: string, status: number }`.
- Log all 5xx errors with request context. Never log request bodies containing PII.
- Keep route handlers thin — delegate business logic to service modules.
```
### Cursor equivalent (`rules/api-routes.mdc`)
```markdown
---
description: "Conventions for API route handlers using Hono"
globs: "src/api/**"
alwaysApply: false
---
- Use Hono framework patterns for route handlers.
- Validate request bodies with Zod schemas before processing.
- Return consistent error shapes: `{ error: string, code: string, status: number }`.
- Log all 5xx errors with request context. Never log request bodies containing PII.
- Keep route handlers thin — delegate business logic to service modules.
```
### Claude Code equivalent (`.claude/rules/api-routes.md`)
```markdown
---
paths:
- "src/api/**"
---
# API Route Conventions
- Use Hono framework patterns for route handlers.
- Validate request bodies with Zod schemas before processing.
- Return consistent error shapes: `{ error: string, code: string, status: number }`.
- Log all 5xx errors with request context. Never log request bodies containing PII.
- Keep route handlers thin — delegate business logic to service modules.
```
---
## Example 2 — Python / FastAPI backend
### Root instructions (`copilot-instructions.md`)
```markdown
# Copilot Instructions
## Language
- Use Python 3.12+. Use type hints for all function signatures.
- Use `ruff` for linting and formatting. Do not use `black` or `isort` separately.
## Architecture
- Follow hexagonal architecture: `domain/`, `adapters/`, `ports/`.
- Domain layer must not import from adapters or infrastructure.
## Naming
- Use `snake_case` for functions, variables, and modules.
- Use `PascalCase` for classes.
- Prefix private methods with underscore.
## Testing
- Use `pytest`. Place tests in `tests/` mirroring `src/` structure.
- Use factories (not fixtures) for test data setup.
- Target 80% coverage minimum for new code.
## Dependencies
- Pin all dependencies in `pyproject.toml`.
- Avoid adding new dependencies without team review.
```
### Scoped instruction (`instructions/db-models.instructions.md`)
```markdown
---
applyTo: "src/adapters/db/**"
---
- Use SQLAlchemy 2.0 declarative style with `Mapped[]` type annotations.
- Every model must define `__tablename__` explicitly.
- Use Alembic for migrations. Never modify the database schema directly.
- Add an index for any column used in WHERE clauses or JOINs.
- Include `created_at` and `updated_at` timestamps on all tables.
```
### Cursor equivalent (`rules/db-models.mdc`)
```markdown
---
description: "SQLAlchemy model and migration conventions"
globs: "src/adapters/db/**"
alwaysApply: false
---
- Use SQLAlchemy 2.0 declarative style with `Mapped[]` type annotations.
- Every model must define `__tablename__` explicitly.
- Use Alembic for migrations. Never modify the database schema directly.
- Add an index for any column used in WHERE clauses or JOINs.
- Include `created_at` and `updated_at` timestamps on all tables.
```
### Claude Code equivalent (`.claude/rules/db-models.md`)
```markdown
---
paths:
- "src/adapters/db/**"
---
# Database Model Conventions
- Use SQLAlchemy 2.0 declarative style with `Mapped[]` type annotations.
- Every model must define `__tablename__` explicitly.
- Use Alembic for migrations. Never modify the database schema directly.
- Add an index for any column used in WHERE clauses or JOINs.
- Include `created_at` and `updated_at` timestamps on all tables.
```
---
## Example 3 — C# / .NET service
### Root instructions (`copilot-instructions.md`)
```markdown
# Copilot Instructions
## Language and framework
- Use C# 12 with .NET 8. Enable nullable reference types.
- Use minimal APIs for new endpoints. Do not use controller-based routing.
## Naming
- Follow Microsoft naming guidelines: PascalCase for public members, camelCase for locals.
- Prefix interfaces with `I` and use PascalCase (for example, `IOrderRepository`).
## Architecture
- Use vertical slice architecture. Each feature gets its own folder.
- Use MediatR for command/query separation.
## Error handling
- Use Result<T> pattern for domain operations.
- Map domain errors to HTTP status codes at the API boundary only.
- Never throw exceptions for expected business rule violations.
## Testing
- Use xUnit with FluentAssertions.
- Use Testcontainers for integration tests with real databases.
- Keep unit tests focused on one behavior per test method.
```
---
## Anti-patterns to avoid
### ❌ Too vague
```markdown
Write good code. Follow best practices. Keep things clean.
```
**Why it fails:** Not actionable. Copilot cannot derive specific conventions from this.
### ❌ Too verbose / explanatory
```markdown
When writing TypeScript code, it is generally considered a best practice to use
the `interface` keyword rather than the `type` keyword when defining object shapes.
This is because interfaces support declaration merging and provide better error
messages in many cases. However, there are situations where type aliases are more
appropriate, such as when defining union types or mapped types...
```
**Why it fails:** Wastes context window on explanation instead of giving a directive. Better version: "Prefer `interface` over `type` for object shapes."
### ❌ Duplicated between root and scoped
Root file says: "Use Zod for validation."
Scoped `api.instructions.md` also says: "Use Zod for validation."
**Why it fails:** Redundant instructions dilute context. Put shared conventions in root only.
### ❌ Overly broad glob
```yaml
# GitHub Copilot
applyTo: "**/*"
# Cursor
globs: "**/*"
# Claude Code
paths:
- "**/*"
```
**Why it fails:** Matches every file — use root instructions (`copilot-instructions.md`), `alwaysApply: true` (Cursor), or `CLAUDE.md` / rule without `paths` (Claude Code) instead.
### ❌ Includes secrets or environment specifics
```markdown
Use API key `sk-abc123...` for the staging environment.
Connect to database at `postgres://admin:password@prod-db:5432`.
```
**Why it fails:** Secrets must never appear in instruction files. Use environment variables and reference them by name only.
SKILL.md
---
name: fusion-rule-author
description: 'Support skill providing the workflow, templates, and references for AI coding assistant rule authoring. Invoked by fusion-rules gateway agents — not intended for direct use.'
license: MIT
metadata:
version: "0.1.1"
status: active
owner: "@equinor/fusion-core"
role: support
tags:
- copilot
- cursor
- claude-code
- rules
- developer-experience
- onboarding
- repository-setup
- system
---
# Rule Author
Canonical workflow, templates, and references for authoring AI coding assistant rules. Supports **GitHub Copilot**, **Cursor**, and **Claude Code**.
> **Internal skill.** Users interact via the `fusion-rules` gateway, which routes to editor-specific agents that follow the workflow defined here.
## Scope
This skill provides:
- **Workflow** (Steps 1–7 below) — the guided authoring process
- **Templates** (`assets/`) — starter files for each editor format
- **References** (`references/`) — tech-stack examples
It does **not** provide agents. Agents live in `fusion-rules/agents/` and reference this skill's assets and workflow.
## Required inputs
### Mandatory
- [ ] Repository context (working directory or repo URL)
### Gathered during interview
- [ ] Tech stack (languages, frameworks, build tools)
- [ ] Code conventions (naming, formatting, patterns)
- [ ] Testing expectations (framework, coverage, style)
- [ ] Documentation preferences (comments, TSDoc/JSDoc, README standards)
- [ ] Commit and PR conventions
- [ ] Error handling patterns
- [ ] Security or compliance constraints
- [ ] File/path-specific conventions that need scoped rules
## Instructions
### Step 1 — Assess current state
Check the repository for existing rule files:
```
.github/copilot-instructions.md
.github/instructions/*.instructions.md
.cursor/rules/*.md
.cursor/rules/*.mdc
.cursor/rules/**/*.md
.cursor/rules/**/*.mdc
CLAUDE.md
.claude/CLAUDE.md
.claude/rules/*.md
.claude/rules/**/*.md
```
Report what exists, what is missing, and whether updates or new files are needed.
### Step 2 — Scan repository
Before interviewing, scan for existing documentation and configuration that encodes conventions. Extract actionable directives from:
**Documentation files:**
- `README.md` — project overview, setup, tech stack
- `CONTRIBUTING.md` — code style, PR workflow, commit conventions
- `AGENTS.md`, `CLAUDE.md` — existing AI instructions
- `docs/adr/**`, `adr/**`, `docs/decisions/**` — Architecture Decision Records
- `docs/**/*.md` — developer guides, onboarding docs, style guides
- `SECURITY.md` — security policies
- `CODE_OF_CONDUCT.md` — collaboration guidelines (rarely rule-relevant)
**Configuration files:**
- `package.json` / `pyproject.toml` / `*.csproj` — tech stack, scripts, dependencies
- `tsconfig.json` / `jsconfig.json` — language settings, strictness
- `biome.json` / `.eslintrc*` / `.prettierrc*` / `ruff.toml` / `.editorconfig` — formatting and linting
- `.github/workflows/*.yml` — CI checks, required validations, test commands
- `Dockerfile` / `docker-compose.yml` — runtime environment
- `Makefile` / `Justfile` / `Taskfile.yml` — build and task commands
**Code patterns (sample, don't exhaustively read):**
- Entry points (`src/index.*`, `src/main.*`, `app.*`) — architecture patterns
- Test files — testing framework, naming conventions, file placement
- Directory structure — architectural boundaries, feature organization
**For each source, extract:**
1. Concrete conventions that can become imperative directives
2. Build/test/lint commands the AI should know
3. Architecture boundaries or patterns to follow
4. Explicit "do this / don't do that" rules
**Skip:**
- Implementation details that change frequently
- Content that restates language/framework defaults
- Aspirational rules not enforced by CI or team practice
Present summary of discovered conventions to the developer, organized by area, before proceeding to the interview.
### Step 3 — Interview (fill gaps)
Use scan results to skip areas already well-documented. Ask focused questions only for gaps. Cover these areas one at a time:
1. **Tech stack** — languages, frameworks, runtime, package manager
2. **Code style** — naming conventions, formatting rules, import ordering
3. **Architecture** — project structure, key patterns (MVC, hexagonal, etc.)
4. **Testing** — framework, conventions, coverage expectations
5. **Documentation** — inline comments style, doc generation, README standards
6. **Git workflow** — branch naming, commit message format, PR expectations
7. **Security** — sensitive data handling, auth patterns, compliance rules
8. **Path-specific concerns** — directories or file types needing specialized guidance
For each area, present what the scan found and ask: "Is this accurate? Anything to add or correct?" Don't re-ask for information already captured.
For each convention needing deeper context, use follow-up questions in `assets/creation-follow-up.md` — purpose, exceptions, boundaries, voice.
### Step 4 — Classify guidance
Separate the gathered conventions into buckets:
**GitHub Copilot:**
| Bucket | Target file | When it activates |
|--------|-------------|-------------------|
| **Always-on** conventions | `.github/copilot-instructions.md` | Every Copilot interaction |
| **Scoped** conventions | `.github/instructions/<name>.instructions.md` | Only when matching files are open/referenced |
**Cursor:**
| Bucket | Target file | When it activates |
|--------|-------------|-------------------|
| **Always-on** conventions | `.cursor/rules/<name>.mdc` with `alwaysApply: true` | Every Cursor Agent session |
| **Auto-attached** conventions | `.cursor/rules/<name>.mdc` with `globs` | When matching files are in context |
| **Agent-selected** conventions | `.cursor/rules/<name>.mdc` with `description` only | When the Agent decides it is relevant |
| **Manual** conventions | `.cursor/rules/<name>.mdc` (no `alwaysApply`, no `globs`) | Only when @-mentioned in chat |
**Claude Code:**
| Bucket | Target file | When it activates |
|--------|-------------|-------------------|
| **Always-on** conventions | `CLAUDE.md` or `.claude/CLAUDE.md` | Every Claude Code session |
| **Scoped** conventions | `.claude/rules/<name>.md` with `paths` frontmatter | When Claude reads matching files |
| **Unconditional rule** | `.claude/rules/<name>.md` (no `paths`) | Every session (like always-on) |
**Decision rule:** If a convention applies to all files in the repo, it belongs in root / always-on instructions. If it applies only to specific paths or file types, create a scoped rule.
When targeting multiple editors, generate parallel files with equivalent content — do not duplicate guidance within a single editor's files.
### Step 5 — Draft rule files
Generate files using templates in `assets/`:
**GitHub Copilot:**
- Root instructions: use `assets/copilot-instructions-template.md`
- Scoped instructions: use `assets/scoped-rule-template.md` with correct `applyTo` glob
**Cursor:**
- Use `assets/cursor-rule-template.mdc` and set frontmatter accordingly
**Claude Code:**
- Project instructions: use `assets/claude-rule-template.md`
- Scoped rules: place in `.claude/rules/` with `paths` frontmatter
**Quality rules (enforced during drafting):**
- Keep instructions concise — actionable directives, not explanations
- Use imperative voice ("Use camelCase for variables", not "Variables should use camelCase")
- Avoid duplicating guidance between root and scoped files
- Validate `applyTo` / `globs` / `paths` glob patterns match intended files
- Warn if total root instructions exceed ~80 lines (risk of context dilution)
- Warn if scoped instruction file exceeds ~50 lines (GitHub Copilot), ~500 lines (Cursor), ~200 lines (Claude Code CLAUDE.md)
- See `references/examples.md` for concrete good/bad examples
- See `assets/quality-checklist.md` for full checklist
### Step 6 — Review and refine
Present drafted files to the developer. For each file:
1. Show full content
2. Highlight quality warnings (length, broad globs, duplication)
3. Ask for approval or edits
### Step 7 — Write files
After approval, write rule files to the repository. Create `.github/instructions/`, `.cursor/rules/`, and/or `.claude/rules/` directories as needed.
Confirm final file list and paths before writing.
## Expected output
- `.github/copilot-instructions.md` — root instructions file (created or updated)
- `.github/instructions/*.instructions.md` — zero or more scoped instruction files
- `.cursor/rules/*.mdc` — zero or more Cursor rule files (when Cursor is targeted)
- `CLAUDE.md` or `.claude/CLAUDE.md` — project instructions (when Claude Code is targeted)
- `.claude/rules/*.md` — zero or more Claude Code scoped rule files
- Summary of what was created/updated and why
## Instructions vs skills vs rules — when to use which
| Need | GitHub Copilot | Cursor | Claude Code |
|------|---------------|--------|-------------|
| Always-on coding conventions | `copilot-instructions.md` | `.cursor/rules/*.mdc` with `alwaysApply: true` | `CLAUDE.md` |
| File/path-specific guidance | `.github/instructions/*.instructions.md` | `.cursor/rules/*.mdc` with `globs` | `.claude/rules/*.md` with `paths` |
| Task-specific multi-step workflows | A skill (`SKILL.md`) | `.cursor/rules/*.mdc` (manual or agent-selected) | Skills / subagents |
| Agent routing and orchestration | Agent definitions (`.agent.md`) | `.cursor/rules/*.mdc` with `description` | Subagent configs |
| Simple project-wide instructions | `copilot-instructions.md` | `AGENTS.md` | `CLAUDE.md` |
Instructions and rules shape **how** the AI writes code. Skills define **what** it can do as structured tasks.
## Safety and constraints
Never:
- Embed secrets, tokens, or credentials in rule files
- Generate rules that contradict repository security policies
- Overwrite existing files without showing the diff and getting approval
- Invent conventions — only document what the developer confirms
Always:
- Show drafts before writing any files
- Validate glob patterns against actual repository paths
- Warn on overly broad globs (e.g., `**/*` captures everything)
- Keep instructions concise and actionable
- Preserve existing content when updating (append or merge, never replace silently)
## References
- `references/examples.md` — concrete examples for different tech stacks
- `assets/creation-follow-up.md` — per-rule follow-up questions (purpose, exceptions, boundaries, voice)
- `assets/frontmatter-scenarios.md` — scenario-based frontmatter guide for GitHub Copilot, Cursor, and Claude Code
- `assets/copilot-instructions-template.md` — starter template for root instructions
- `assets/scoped-rule-template.md` — starter template for scoped rules
- `assets/cursor-rule-template.mdc` — starter template for Cursor rules
- `assets/claude-rule-template.md` — starter template for Claude Code rules
- `assets/quality-checklist.md` — quality review checklist