From: XinqiBao <35754562+XinqiBao@users.noreply.github.com> Date: Mon, 23 Feb 2026 02:29:12 +0000 (+0800) Subject: feat(claude): add xdev workflow configuration X-Git-Url: https://git.xinqibao.xyz/dotfiles.git/commitdiff_plain/ff2ea1e70c415b567555f727c30d2dcc04a0d90e?ds=sidebyside;hp=5789e3625ffd9d300634c84e97f986742cac4c7c feat(claude): add xdev workflow configuration Global CLAUDE.md with dev principles, three xdev commands (implement, draft, setup), and install script for symlinks. --- diff --git a/claude/CLAUDE.md b/claude/CLAUDE.md new file mode 100644 index 0000000..eca1529 --- /dev/null +++ b/claude/CLAUDE.md @@ -0,0 +1,53 @@ +# Development Principles + +## Quality +- Quality over speed. Skip uncertain tasks rather than deliver bad code. +- Keep solutions minimal. No extra abstractions or "just in case" code. +- Stay strictly within the scope of the task. Do not refactor or improve + surrounding code unless explicitly asked. + +## Decision Making +- If multiple valid approaches exist, discuss with the user before choosing. + Do NOT pick one silently. +- If a change involves new abstractions, new patterns, or structural changes + not explicitly requested in the task, discuss first. +- When uncertain about any design decision, ask rather than guess. +- Follow existing codebase patterns unless the task specifically requires + changing them. If you believe structural changes are needed beyond the + task scope, raise it as a separate concern. + +## Context Management +- Complete the entire task within a single context window. +- If a task is clearly too large for one context, suggest splitting it + into smaller tasks before starting. +- When making incremental progress, commit working code frequently so + progress is preserved in git. + +# Git Commit Convention + +Follow Conventional Commits strictly: + +## Format +``` +(): +``` + +## Rules +- type: feat/fix/refactor/docs/test/chore/perf/build +- scope: optional, module or component name +- subject: imperative mood, lowercase, no period, max 50 chars +- English only +- Focus on WHAT changed, not WHY or HOW you thought about it +- Be concise and direct +- No emoji, no AI markers, no co-author footer, no "Generated by" text + +## Good examples +- `feat(order): add limit order support` +- `fix(gateway): handle reconnection on market data timeout` +- `refactor(engine): simplify order state machine` +- `perf(matching): reduce memory allocation in hot path` + +## Bad examples +- `feat: Added new feature for better user experience` (vague, past tense) +- `fix: Fix the bug that was causing issues` (redundant) +- `update code` (no type, meaningless) diff --git a/claude/commands/xdev-draft.md b/claude/commands/xdev-draft.md new file mode 100644 index 0000000..5549364 --- /dev/null +++ b/claude/commands/xdev-draft.md @@ -0,0 +1,28 @@ +Help the user draft a well-structured issue for their project's +issue tracker. + +## Process + +1. Ask the user to describe what they want in their own words. +2. Ask clarifying questions (one at a time) to understand: + - What is the problem or desired outcome? + - What is the current behavior vs expected behavior? + - Are there constraints or preferences? +3. Draft a structured issue with: + - Title: `type(scope): concise description` + - Body: + - **Context**: why this is needed (1-2 sentences) + - **Goal**: what should change (concrete, testable) + - **Acceptance criteria**: how to verify it's done + - **Constraints** (if any): what NOT to do, what to preserve +4. Present the draft to the user for review. +5. If the user approves, submit using whatever tool is available + (gh, glab, MCP), or output the formatted text for manual submission. + +## Principles + +- Intent-driven: describe WHAT and WHY, not HOW to implement. +- Give implementation space: do not over-specify the approach. +- One issue = one change. If the idea is too big, suggest splitting + into multiple issues. +- Include acceptance criteria so the implementer knows when it's done. diff --git a/claude/commands/xdev-implement.md b/claude/commands/xdev-implement.md new file mode 100644 index 0000000..61514ba --- /dev/null +++ b/claude/commands/xdev-implement.md @@ -0,0 +1,45 @@ +You are handling an issue from the project's issue tracker. +Follow this SOP strictly. + +## Step 1: Understand + +- Fetch the issue content (title, body, labels, comments). + Use whatever tool is available (gh, glab, MCP, or ask the user to provide). +- Read the project's CLAUDE.md and understand the codebase structure. +- Identify the scope: what files are likely affected, what tests exist. + +## Step 2: Assess Complexity + +Before writing any code, assess: +- Is the issue clear enough to implement? If not, ask the user for clarification. +- Are there multiple valid approaches? If yes, present them with trade-offs + and let the user choose. Do NOT pick one silently. +- Is this too large for a single context? If yes, suggest splitting into + smaller issues before starting. + +## Step 3: Branch and Implement + +- Create a feature branch: `/issue--` +- Implement the change following existing codebase patterns. +- Write tests for the change (unless pure documentation). +- Make small, focused commits using Conventional Commits format. + +## Step 4: Validate + +Before submitting: +- All existing tests still pass. +- New tests cover the changes. +- Changes are limited to issue scope. +- No unnecessary refactoring or additions. + +## Step 5: Submit + +- Push the branch and create a merge/pull request linking the issue. +- Title: concise summary. Body: what changed and why. + +## Escape Hatch + +If at any point: +- The issue is unclear → ask the user, do not guess. +- The implementation risk is too high → explain the risk and stop. +- The scope is larger than expected → suggest splitting into multiple issues. diff --git a/claude/commands/xdev-setup.md b/claude/commands/xdev-setup.md new file mode 100644 index 0000000..e54dff6 --- /dev/null +++ b/claude/commands/xdev-setup.md @@ -0,0 +1,98 @@ +Analyze the current project and generate a health report. Then guide +the user through setting up CLAUDE.md if one doesn't exist. + +## Step 1: Project Analysis + +Scan the project root and report findings for each quality dimension. +Do not assume any specific language or toolchain. + +### Build System +Detect build files: CMakeLists.txt, Makefile, meson.build, package.json, +pyproject.toml, setup.py, Cargo.toml, go.mod, build.gradle, pom.xml, +or other build configuration. +Report what was found, or note "no build system detected". + +### Testing +Detect test directories: tests/, test/, __tests__/, spec/, or test +files matching common patterns (*_test.*, test_*.*, *.spec.*, *_spec.*). +Detect test runner config: pytest.ini, jest.config.*, .mocharc.*, +CTestTestfile.cmake, Catch2/GoogleTest headers, etc. +Report what was found. + +### Code Quality Tools +Detect formatter/linter config: .clang-format, .clang-tidy, .eslintrc*, +.prettierrc*, pyproject.toml [tool.ruff/black/flake8], rustfmt.toml, +.editorconfig, .golangci.yml, or similar. +Detect git hooks: .pre-commit-config.yaml, .husky/, .githooks/. +Report what was found. + +### CI/CD +Detect: .github/workflows/, .gitlab-ci.yml, Jenkinsfile, .circleci/, +.travis.yml, bitbucket-pipelines.yml, or similar. +Report what was found. + +### Documentation +Check: README.md and CLAUDE.md existence. If they exist, note whether +they have meaningful content beyond just a title. + +## Step 2: Report + +Present findings as a concise checklist: + +``` +Project Health Report: + Build system: ✓ CMake (CMakeLists.txt) + Tests: ✓ tests/ directory, GoogleTest + Code quality: ✓ .clang-format, .clang-tidy, pre-commit + CI/CD: ✗ No CI configuration found + README: ✓ Exists with content + CLAUDE.md: ✗ Missing +``` + +For each ✗ item, provide a brief, actionable suggestion. +Do NOT mandate specific tools — suggest based on what fits the project. + +## Step 3: CLAUDE.md Creation (if missing or inadequate) + +If CLAUDE.md doesn't exist or is just a placeholder, guide the user: + +1. Ask about the project's purpose (one sentence). +2. Document detected build/test commands. +3. Ask about key code conventions or architectural constraints. +4. Generate a minimal CLAUDE.md (under 50 lines) following this structure: + +```markdown +# + + + +## Quick Reference + +\```bash +# Build + + +# Test + +\``` + +## Code Conventions + +- +- + +## Constraints + +- +- +- +``` + +Do NOT over-generate. A 20-line CLAUDE.md with accurate info is better +than a 100-line one with guesses. + +## Step 4: Hooks Suggestion (optional) + +If a code formatter is detected, suggest a PostToolUse hook configuration +that auto-formats after edits. Present the suggestion and let the user +decide whether to add it to `.claude/settings.local.json`. diff --git a/install-claude.sh b/install-claude.sh new file mode 100755 index 0000000..55ba91f --- /dev/null +++ b/install-claude.sh @@ -0,0 +1,27 @@ +#!/usr/bin/env bash +set -euo pipefail + +SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)" +CLAUDE_DIR="$HOME/.claude" + +echo "Installing Claude Code configuration..." + +# Backup existing CLAUDE.md if it exists and is not a symlink +if [ -f "$CLAUDE_DIR/CLAUDE.md" ] && [ ! -L "$CLAUDE_DIR/CLAUDE.md" ]; then + echo "Backing up existing CLAUDE.md to CLAUDE.md.bak" + cp "$CLAUDE_DIR/CLAUDE.md" "$CLAUDE_DIR/CLAUDE.md.bak" +fi + +# Symlink CLAUDE.md +ln -sf "$SCRIPT_DIR/claude/CLAUDE.md" "$CLAUDE_DIR/CLAUDE.md" +echo " ✓ CLAUDE.md" + +# Symlink commands +mkdir -p "$CLAUDE_DIR/commands" +for cmd in "$SCRIPT_DIR"/claude/commands/xdev-*.md; do + [ -f "$cmd" ] || continue + ln -sf "$cmd" "$CLAUDE_DIR/commands/$(basename "$cmd")" + echo " ✓ commands/$(basename "$cmd")" +done + +echo "Done. Claude Code xdev workflow installed."