From 33186f1a9312c736fa19ed3820c8646341a7a8f7 Mon Sep 17 00:00:00 2001
From: Mark L <73659136+liuxiaopai-ai@users.noreply.github.com>
Date: Mon, 9 Feb 2026 08:12:05 +0800
Subject: [PATCH] fix: preserve directory structure in installation to prevent
 file overwrites (#169)

Fix installation instructions that caused file overwrites. Adds install.sh script and preserves directory structure. Fixes #164.
---
 install.sh      | 51 +++++++++++++++++++++++++++++++++++++++++++++++++
 rules/README.md | 29 +++++++++++++++++++++++-----
 2 files changed, 75 insertions(+), 5 deletions(-)
 create mode 100755 install.sh

diff --git a/install.sh b/install.sh
new file mode 100755
index 00000000..20fbf480
--- /dev/null
+++ b/install.sh
@@ -0,0 +1,51 @@
+#!/usr/bin/env bash
+# install.sh — Install claude rules while preserving directory structure.
+#
+# Usage:
+#   ./install.sh <language> [<language> ...]
+#
+# Examples:
+#   ./install.sh typescript
+#   ./install.sh typescript python golang
+#
+# This script copies rules into ~/.claude/rules/ keeping the common/ and
+# language-specific subdirectories intact so that:
+#   1. Files with the same name in common/ and <language>/ don't overwrite
+#      each other.
+#   2. Relative references (e.g. ../common/coding-style.md) remain valid.
+
+set -euo pipefail
+
+RULES_DIR="$(cd "$(dirname "$0")/rules" && pwd)"
+DEST_DIR="${CLAUDE_RULES_DIR:-$HOME/.claude/rules}"
+
+if [[ $# -eq 0 ]]; then
+    echo "Usage: $0 <language> [<language> ...]"
+    echo ""
+    echo "Available languages:"
+    for dir in "$RULES_DIR"/*/; do
+        name="$(basename "$dir")"
+        [[ "$name" == "common" ]] && continue
+        echo "  - $name"
+    done
+    exit 1
+fi
+
+# Always install common rules
+echo "Installing common rules -> $DEST_DIR/common/"
+mkdir -p "$DEST_DIR/common"
+cp -r "$RULES_DIR/common/." "$DEST_DIR/common/"
+
+# Install each requested language
+for lang in "$@"; do
+    lang_dir="$RULES_DIR/$lang"
+    if [[ ! -d "$lang_dir" ]]; then
+        echo "Warning: rules/$lang/ does not exist, skipping." >&2
+        continue
+    fi
+    echo "Installing $lang rules -> $DEST_DIR/$lang/"
+    mkdir -p "$DEST_DIR/$lang"
+    cp -r "$lang_dir/." "$DEST_DIR/$lang/"
+done
+
+echo "Done. Rules installed to $DEST_DIR/"
diff --git a/rules/README.md b/rules/README.md
index 3153d600..57de9d38 100644
--- a/rules/README.md
+++ b/rules/README.md
@@ -25,17 +25,36 @@ rules/
 
 ## 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 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/
+cp -r rules/common ~/.claude/rules/common
 
 # Install language-specific rules based on your project's tech stack
-cp -r rules/typescript/* ~/.claude/rules/
-cp -r rules/python/* ~/.claude/rules/
-cp -r rules/golang/* ~/.claude/rules/
+cp -r rules/typescript ~/.claude/rules/typescript
+cp -r rules/python ~/.claude/rules/python
+cp -r rules/golang ~/.claude/rules/golang
 
 # Attention ! ! ! Configure according to your actual project requirements; the configuration here is for reference only.
-
 ```
 
 ## Rules vs Skills