chore(claude): optimize config for agentic coding (#606)

Author: Chemaclass

.claude/CLAUDE.md

@@ -20,7 +20,7 @@ Works on macOS default bash. **Prohibited features:**
 - `${array[-1]}` (negative indexing - Bash 4.3+)
 - `&>>` redirect (Bash 4.0+)
 
-See @.claude/rules/bash-style.md for complete compatibility guide.
+See `.claude/rules/bash-style.md` for complete compatibility guide (auto-loaded when editing `src/` or `tests/`).
 
 ### Quality Standards
 
@@ -90,19 +90,10 @@ Invoke with `/skill-name`:
 | `/gh-issue <N>` | GitHub issue → branch → implement → PR |
 | `/pr [#N]` | Push branch and create PR |
 
-## Code Standards
-
-### Bash Style
-@.claude/rules/bash-style.md
-
-### Testing
-@.claude/rules/testing.md
-
-### TDD Workflow
-@.claude/rules/tdd-workflow.md
-
 ## Path-Scoped Guidelines
 
+Rules auto-load based on file paths being edited (via `paths:` frontmatter in each rule file).
+
 ### `src/**/*.sh`
 - Small, portable functions
 - Bash 3.0+ compatibility (no associative arrays, no `[[`, no `${var,,}`)

.claude/rules/bash-style.md

@@ -10,322 +10,48 @@ paths:
 
 bashunit must work on **Bash 3.0+** (macOS default). These features are **prohibited**:
 
-### ❌ Forbidden Features
+| Feature | Bash ver | Alternative |
+|---------|----------|-------------|
+| `declare -A` (associative arrays) | 4.0+ | Parallel indexed arrays |
+| `[[ ]]` (test operator) | — | `[ ]` with `=` not `==` |
+| `${var,,}` / `${var^^}` (case) | 4.0+ | `tr '[:upper:]' '[:lower:]'` |
+| `${array[-1]}` (negative index) | 4.3+ | `${array[${#array[@]}-1]}` |
+| `&>>` (append both) | 4.0+ | `>> file 2>&1` |
 
-**Associative arrays** (Bash 4.0+):
-```bash
-# ❌ DON'T
-declare -A map
-map["key"]="value"
-
-# ✅ DO - Use indexed arrays or workarounds
-declare -a keys=("key1" "key2")
-declare -a values=("val1" "val2")
-```
-
-**`[[` test operator** - Use `[` instead:
-```bash
-# ❌ DON'T
-if [[ "$var" == "value" ]]; then
-
-# ✅ DO
-if [ "$var" = "value" ]; then
-```
-
-**Case conversion** (`${var,,}`, `${var^^}`):
-```bash
-# ❌ DON'T
-lowercase="${var,,}"
-
-# ✅ DO
-lowercase=$(echo "$var" | tr '[:upper:]' '[:lower:]')
-```
-
-**Negative array indexing** (`${array[-1]}`):
-```bash
-# ❌ DON'T
-last="${array[-1]}"
-
-# ✅ DO
-last="${array[${#array[@]}-1]}"
-```
-
-**`&>>` redirect** (Bash 4.0+):
-```bash
-# ❌ DON'T
-command &>> file
-
-# ✅ DO
-command >> file 2>&1
-```
-
-## Coding Style
-
-Follow [Google Shell Style Guide](https://google.github.io/styleguide/shellguide.html) with these specifics:
-
-### Indentation & Formatting
-
-- **2 spaces** (no tabs)
-- Use `shfmt -w .` to format
-- Maximum line length: 120 characters (soft limit)
-
-### Function Naming
-
-**Namespace all public functions:**
-```bash
-# ✅ Public functions
-function bashunit::assert_equals() { ... }
-function bashunit::mock() { ... }
-
-# ✅ Private/internal functions (leading underscore)
-function _internal_helper() { ... }
-```
-
-### Variable Naming
-
-```bash
-# ✅ Local variables - lowercase with underscores
-local test_name="example"
-local file_path="/path/to/file"
-
-# ✅ Global/exported - uppercase
-export BASHUNIT_LOG_JUNIT="false"
-readonly BASHUNIT_VERSION="0.32.0"
-
-# ✅ Function parameters - clear names
-function process_file() {
-  local input_file="$1"
-  local output_dir="${2:-./output}"
-}
-```
+## Coding Conventions
 
-### Quoting
+- **2 spaces** indent, no tabs — enforced by `shfmt -w .`
+- **120 chars** max line length (soft)
+- Follow [Google Shell Style Guide](https://google.github.io/styleguide/shellguide.html)
+- Always quote variables unless explicit word splitting is needed
+- Use `$()` for command substitution, never backticks
 
-**Always quote variables** unless you explicitly need word splitting:
+### Naming
 
-```bash
-# ✅ DO
-echo "$variable"
-[[ -f "$file_path" ]]
-command --arg="$value"
-
-# ❌ DON'T (unless intentional word splitting)
-echo $variable
-[[ -f $file_path ]]
-```
-
-### Error Handling
+- **Public functions:** `bashunit::function_name`
+- **Private functions:** `_function_name` (leading underscore)
+- **Local variables:** `lowercase_with_underscores`
+- **Globals/exports:** `UPPERCASE_WITH_UNDERSCORES`
 
-Use `set -euo pipefail` judiciously:
-
-```bash
-# ✅ In scripts
-#!/usr/bin/env bash
-set -euo pipefail
-
-# ⚠️ In functions - be cautious
-# Don't use in functions that expect to handle failures
-function might_fail() {
-  local result
-  result=$(command_that_might_fail) || return 1
-  echo "$result"
-}
-```
-
-### Function Documentation
-
-Document all public functions:
+### Function Docs (public functions)
 
 ```bash
 ##
-# Brief description of what the function does
-#
-# Arguments:
-#   $1 - First parameter description
-#   $2 - Second parameter description (optional, default: "value")
-#
-# Returns:
-#   0 on success
-#   1 on validation failure
-#   2 on execution error
-#
-# Example:
-#   bashunit::my_function "input" "optional"
+# Brief description
+# Arguments: $1 - desc, $2 - desc (optional, default: "x")
+# Returns: 0 success, 1 failure
 ##
-function bashunit::my_function() {
-  local required="$1"
-  local optional="${2:-default}"
-
-  # Implementation
-}
 ```
 
-## ShellCheck Compliance
-
-All code must pass ShellCheck:
-
-```bash
-make sa
-# or
-shellcheck -x $(find . -name "*.sh")
-```
-
-**Common directives:**
-
-```bash
-# Disable specific check with reason
-# shellcheck disable=SC2034  # Variable appears unused
-local unused_var="value"
-
-# Source external file for shellcheck
-# shellcheck source=src/assertions.sh
-source "$(dirname "${BASH_SOURCE[0]}")/assertions.sh"
-```
-
-## Portability
-
-### Path Handling
-
-```bash
-# ✅ Use BASH_SOURCE for relative paths
-script_dir="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
-
-# ✅ Use dirname/basename
-parent_dir="$(dirname "$file_path")"
-filename="$(basename "$file_path")"
-```
-
-### Command Substitution
-
-```bash
-# ✅ Use $() instead of backticks
-result=$(command arg1 arg2)
-
-# ❌ DON'T
-result=`command arg1 arg2`
-```
-
-### Temporary Files
-
-```bash
-# ✅ Use bashunit globals
-echo "content" > "$temp_file"
-mkdir -p "$temp_dir"
-
-# ⚠️ If creating manually, ensure cleanup
-cleanup() {
-  rm -rf "$temp_file"
-}
-trap cleanup EXIT
-```
-
-## Performance Considerations
-
-### Avoid Subshells When Possible
-
-```bash
-# ✅ Better
-local count=0
-while read -r line; do
-  ((count++))
-done < file
-
-# ⚠️ Slower (creates subshell)
-local count
-count=$(wc -l < file)
-```
-
-### Use Built-ins Over External Commands
-
-```bash
-# ✅ Built-in
-[[ -f "$file" ]] && echo "exists"
-
-# ⚠️ External command (slower)
-test -f "$file" && echo "exists"
-```
-
-## Code Organization
-
 ### File Structure
 
-```bash
-#!/usr/bin/env bash
-# Brief file description
-
-# Constants
-readonly CONSTANT_VALUE="value"
-
-# Global variables
-declare -g global_var=""
-
-# Private functions
-function _private_helper() { ... }
-
-# Public functions
-function bashunit::public_function() { ... }
-```
-
-### Sourcing Dependencies
-
-```bash
-# ✅ Relative to script location
-source "$(dirname "${BASH_SOURCE[0]}")/dependency.sh"
-
-# ✅ With error checking
-if [[ ! -f "$dependency_path" ]]; then
-  echo "Error: Cannot find dependency" >&2
-  return 1
-fi
-source "$dependency_path"
-```
-
-## Security
-
-### Input Validation
-
-```bash
-# ✅ Validate inputs
-function process_user_input() {
-  local input="$1"
-
-  if [[ -z "$input" ]]; then
-    echo "Error: Input required" >&2
-    return 1
-  fi
-
-  # Process sanitized input
-}
-```
-
-### Safe File Operations
-
-```bash
-# ✅ Check before operations
-if [[ -w "$file" ]]; then
-  echo "data" > "$file"
-fi
-
-# ✅ Use -- to prevent flag injection
-rm -- "$user_provided_file"
-```
-
-## Anti-Patterns to Avoid
+Constants -> Globals -> Private functions -> Public functions
 
-❌ **Global state without cleanup**
-❌ **Unquoted variables**
-❌ **Ignoring command failures silently**
-❌ **Using eval without sanitization**
-❌ **Hardcoded paths** (use relative or configurable)
-❌ **Functions > 50 lines** (refactor into smaller pieces)
-❌ **Deep nesting** (> 3 levels, extract functions)
+Source deps relative to script: `"$(dirname "${BASH_SOURCE[0]}")/dep.sh"`
 
-## Validation
+## ShellCheck
 
-Before committing:
+All code must pass `make sa`. Use directives sparingly with reason:
 ```bash
-make sa          # ShellCheck
-make lint        # EditorConfig
-shfmt -w .       # Format
-./bashunit tests/  # All tests pass
+# shellcheck disable=SC2034  # Variable used by caller
 ```