104 lines
4.1 KiB
Markdown
104 lines
4.1 KiB
Markdown
|
# Rules
|
||
|
|
## Structure
|
||
|
|
|
||
|
|
Rules are organized into a **common** layer plus **language-specific** directories:
|
||
|
|
|
||
|
|
```
|
||
|
|
rules/
|
||
|
|
├── common/ # Language-agnostic principles (always install)
|
||
|
|
│ ├── coding-style.md
|
||
|
|
│ ├── git-workflow.md
|
||
|
|
│ ├── testing.md
|
||
|
|
│ ├── performance.md
|
||
|
|
│ ├── patterns.md
|
||
|
|
│ ├── hooks.md
|
||
|
|
│ ├── agents.md
|
||
|
|
│ └── security.md
|
||
|
|
├── typescript/ # TypeScript/JavaScript specific
|
||
|
|
├── python/ # Python specific
|
||
|
|
├── golang/ # Go specific
|
||
|
|
└── swift/ # Swift specific
|
||
|
|
```
|
||
|
|
|
||
|
|
- **common/** contains universal principles — no language-specific code examples.
|
||
|
|
- **Language directories** extend the common rules with framework-specific patterns, tools, and code examples. Each file references its common counterpart.
|
||
|
|
|
||
|
|
## Installation
|
||
|
|
|
||
|
|
### Option 1: Install Script (Recommended)
|
||
|
|
|
||
|
|
```bash
|
||
|
|
# Install common + one or more language-specific rule sets
|
||
|
|
./install.sh typescript
|
||
|
|
./install.sh python
|
||
|
|
./install.sh golang
|
||
|
|
./install.sh swift
|
||
|
|
|
||
|
|
# Install multiple languages at once
|
||
|
|
./install.sh typescript python
|
||
|
|
```
|
||
|
|
|
||
|
|
### Option 2: Manual Installation
|
||
|
|
|
||
|
|
> **Important:** Copy entire directories — do NOT flatten with `/*`.
|
||
|
|
> Common and language-specific directories contain files with the same names.
|
||
|
|
> Flattening them into one directory causes language-specific files to overwrite
|
||
|
|
> common rules, and breaks the relative `../common/` references used by
|
||
|
|
> language-specific files.
|
||
|
|
|
||
|
|
```bash
|
||
|
|
# Install common rules (required for all projects)
|
||
|
|
cp -r rules/common ~/.claude/rules/common
|
||
|
|
|
||
|
|
# Install language-specific rules based on your project's tech stack
|
||
|
|
cp -r rules/typescript ~/.claude/rules/typescript
|
||
|
|
cp -r rules/python ~/.claude/rules/python
|
||
|
|
cp -r rules/golang ~/.claude/rules/golang
|
||
|
|
cp -r rules/swift ~/.claude/rules/swift
|
||
|
|
|
||
|
|
# Attention ! ! ! Configure according to your actual project requirements; the configuration here is for reference only.
|
||
|
|
```
|
||
|
|
|
||
|
|
## Rules vs Skills
|
||
|
|
|
||
|
|
- **Rules** define standards, conventions, and checklists that apply broadly (e.g., "80% test coverage", "no hardcoded secrets").
|
||
|
|
- **Skills** (`skills/` directory) provide deep, actionable reference material for specific tasks (e.g., `python-patterns`, `golang-testing`).
|
||
|
|
|
||
|
|
Language-specific rule files reference relevant skills where appropriate. Rules tell you *what* to do; skills tell you *how* to do it.
|
||
|
|
|
||
|
|
## Adding a New Language
|
||
|
|
|
||
|
|
To add support for a new language (e.g., `rust/`):
|
||
|
|
|
||
|
|
1. Create a `rules/rust/` directory
|
||
|
|
2. Add files that extend the common rules:
|
||
|
|
- `coding-style.md` — formatting tools, idioms, error handling patterns
|
||
|
|
- `testing.md` — test framework, coverage tools, test organization
|
||
|
|
- `patterns.md` — language-specific design patterns
|
||
|
|
- `hooks.md` — PostToolUse hooks for formatters, linters, type checkers
|
||
|
|
- `security.md` — secret management, security scanning tools
|
||
|
|
3. Each file should start with:
|
||
|
|
```
|
||
|
|
> This file extends [common/xxx.md](../common/xxx.md) with <Language> specific content.
|
||
|
|
```
|
||
|
|
4. Reference existing skills if available, or create new ones under `skills/`.
|
||
|
|
|
||
|
|
## Rule Priority
|
||
|
|
|
||
|
|
When language-specific rules and common rules conflict, **language-specific rules take precedence** (specific overrides general). This follows the standard layered configuration pattern (similar to CSS specificity or `.gitignore` precedence).
|
||
|
|
|
||
|
|
- `rules/common/` defines universal defaults applicable to all projects.
|
||
|
|
- `rules/golang/`, `rules/python/`, `rules/typescript/`, etc. override those defaults where language idioms differ.
|
||
|
|
|
||
|
|
### Example
|
||
|
|
|
||
|
|
`common/coding-style.md` recommends immutability as a default principle. A language-specific `golang/coding-style.md` can override this:
|
||
|
|
|
||
|
|
> Idiomatic Go uses pointer receivers for struct mutation — see [common/coding-style.md](../common/coding-style.md) for the general principle, but Go-idiomatic mutation is preferred here.
|
||
|
|
|
||
|
|
### Common rules with override notes
|
||
|
|
|
||
|
|
Rules in `rules/common/` that may be overridden by language-specific files are marked with:
|
||
|
|
|
||
|
|
> **Language note**: This rule may be overridden by language-specific rules for languages where this pattern is not idiomatic.
|