Skip to content

Commit 3a2dd18

Browse files
WitMiaoWitMiao
committed
feat: add technical execution guidelines and zcf-release command
- Add technical-guides.md with command execution best practices - Add /zcf-release automated release command - Support path handling with quotes for cross-platform compatibility - Prioritize ripgrep for better search performance
1 parent aa79fd1 commit 3a2dd18

5 files changed

Lines changed: 440 additions & 0 deletions

File tree

‎.claude/commands/zcf-release.md‎

Lines changed: 257 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,257 @@
1+
# ZCF Release - Automated Release and Commit
2+
3+
Automate version release and code commit using changeset.
4+
5+
## Usage
6+
7+
```bash
8+
/zcf-release [-p|-mi|-ma]
9+
```
10+
11+
## Parameters
12+
13+
- `-p` or `--patch`: Patch version (default) - bug fixes, minor changes
14+
- `-mi` or `--minor`: Minor version - new features, backward compatible
15+
- `-ma` or `--major`: Major version - breaking changes, incompatible
16+
17+
## Context
18+
19+
- Automatically analyze code changes and generate bilingual CHANGELOG
20+
- Use changeset for version management
21+
- Auto commit code and create release tags
22+
- Support GitHub Actions auto publish to npm
23+
24+
## Your Role
25+
26+
You are a professional release management assistant responsible for:
27+
1. Analyzing code changes
28+
2. Generating standardized CHANGELOG
29+
3. Executing version release process
30+
31+
## Execution Flow
32+
33+
Parse arguments: $ARGUMENTS
34+
35+
### 1. Parameter Parsing
36+
37+
```bash
38+
VERSION_TYPE="patch" # Default to patch version
39+
40+
case "$ARGUMENTS" in
41+
-p|--patch)
42+
VERSION_TYPE="patch"
43+
;;
44+
-mi|--minor)
45+
VERSION_TYPE="minor"
46+
;;
47+
-ma|--major)
48+
VERSION_TYPE="major"
49+
;;
50+
"")
51+
VERSION_TYPE="patch"
52+
;;
53+
*)
54+
echo "Unknown parameter: $ARGUMENTS"
55+
echo "Usage: /zcf-release [-p|-mi|-ma]"
56+
exit 1
57+
;;
58+
esac
59+
60+
echo "🚀 Preparing to release $VERSION_TYPE version"
61+
```
62+
63+
### 2. Check Working Directory Status
64+
65+
Check if the current working directory meets release conditions:
66+
67+
```bash
68+
# Ensure in project root directory
69+
if [ ! -f "package.json" ]; then
70+
echo "❌ Error: package.json not found, please run in project root"
71+
exit 1
72+
fi
73+
74+
# Check for uncommitted changes
75+
if ! git diff --quiet || ! git diff --cached --quiet; then
76+
echo "⚠️ Detected uncommitted changes:"
77+
git status --short
78+
echo ""
79+
read -p "Commit these changes first? [Y/n] " -n 1 -r
80+
echo
81+
if [[ $REPLY =~ ^[Yy]$ ]] || [[ -z $REPLY ]]; then
82+
echo "Please commit changes before releasing"
83+
exit 1
84+
fi
85+
fi
86+
87+
echo "✅ Working directory status OK"
88+
```
89+
90+
### 3. Analyze Version Changes
91+
92+
Analyze all changes since last release:
93+
94+
```bash
95+
# Get last release tag
96+
LAST_TAG=$(git describe --tags --abbrev=0 2>/dev/null || echo "")
97+
98+
if [ -z "$LAST_TAG" ]; then
99+
echo "📊 No previous version tag found, analyzing all commits"
100+
COMMITS=$(git log --oneline)
101+
else
102+
echo "📊 Last version: $LAST_TAG"
103+
echo "Analyzing changes since $LAST_TAG..."
104+
COMMITS=$(git log $LAST_TAG..HEAD --oneline)
105+
fi
106+
107+
# Show commit history
108+
echo -e "\n📝 Changes:"
109+
echo "$COMMITS"
110+
111+
# Analyze file changes
112+
echo -e "\n📁 File change statistics:"
113+
if [ -z "$LAST_TAG" ]; then
114+
git diff --stat
115+
else
116+
git diff --stat $LAST_TAG..HEAD
117+
fi
118+
```
119+
120+
### 4. Generate CHANGELOG Content
121+
122+
Based on code change analysis, I will generate CHANGELOG following these standards:
123+
124+
**Format Requirements**:
125+
1. Chinese description first, English description second
126+
2. No mixing Chinese and English on the same line
127+
3. Organize by category: New Features, Optimization, Fixes, Documentation, etc.
128+
4. Each entry should be concise and clear
129+
130+
**Example Format**:
131+
```markdown
132+
## 新功能
133+
134+
- 添加技术执行指南文档，提供命令执行最佳实践
135+
- 支持自动化发版命令 /zcf-release
136+
- Windows 路径自动加引号处理
137+
138+
## New Features
139+
140+
- Add technical execution guidelines with command best practices
141+
- Support automated release command /zcf-release
142+
- Automatic quote handling for Windows paths
143+
144+
## 优化
145+
146+
- 优先使用 ripgrep 提升搜索性能
147+
- 改进模板文件组织结构
148+
149+
## Optimization
150+
151+
- Prioritize ripgrep for better search performance
152+
- Improve template file organization
153+
154+
## 修复
155+
156+
- 修复 Windows 路径反斜杠丢失问题
157+
158+
## Fixes
159+
160+
- Fix Windows path backslash escaping issue
161+
```
162+
163+
### 5. Create Changeset
164+
165+
Create changeset file based on analysis:
166+
167+
```bash
168+
# Generate timestamp
169+
TIMESTAMP=$(date +%Y%m%d%H%M%S)
170+
CHANGESET_FILE=".changeset/release-$TIMESTAMP.md"
171+
172+
# Create changeset file
173+
echo "📝 Creating changeset file..."
174+
cat > "$CHANGESET_FILE" << 'EOF'
175+
---
176+
"zcf": $VERSION_TYPE
177+
---
178+
179+
[Bilingual CHANGELOG content generated based on actual changes]
180+
EOF
181+
182+
echo "✅ Changeset file created: $CHANGESET_FILE"
183+
```
184+
185+
### 6. Update Version Number
186+
187+
Use changeset to update version number and CHANGELOG:
188+
189+
```bash
190+
echo "🔄 Updating version number and CHANGELOG..."
191+
pnpm changeset version
192+
193+
# Get new version number
194+
NEW_VERSION=$(node -p "require('./package.json').version")
195+
echo "📦 New version: v$NEW_VERSION"
196+
197+
# Show CHANGELOG update
198+
echo -e "\n📋 CHANGELOG has been updated, please review the content"
199+
```
200+
201+
### 7. Create Release Commit
202+
203+
Commit all changes and create version tag:
204+
205+
```bash
206+
echo "💾 Committing release changes..."
207+
208+
# Add all changes
209+
git add .
210+
211+
# Create release commit
212+
git commit -m "chore: release v$NEW_VERSION
213+
214+
- Update version to $NEW_VERSION
215+
- Update CHANGELOG.md
216+
- Generated by /zcf-release command"
217+
218+
# Create tag
219+
git tag -a "v$NEW_VERSION" -m "Release v$NEW_VERSION"
220+
echo "🏷️ Tag created: v$NEW_VERSION"
221+
```
222+
223+
### 8. Push to Remote Repository
224+
225+
```bash
226+
echo "🚀 Pushing to remote repository..."
227+
228+
# Push main branch
229+
git push origin main
230+
231+
# Push tag
232+
git push origin "v$NEW_VERSION"
233+
234+
echo -e "\n✅ Release preparation complete!"
235+
echo "📦 Version v$NEW_VERSION is ready"
236+
echo "🤖 GitHub Actions will automatically publish to npm"
237+
echo "👀 View release status: https://github.com/UfoMiao/zcf/actions"
238+
```
239+
240+
## Complete Workflow Summary
241+
242+
1. **Preparation Phase**: Check parameters, working directory status
243+
2. **Analysis Phase**: Analyze commit history and file changes
244+
3. **Generation Phase**: Create bilingual CHANGELOG
245+
4. **Execution Phase**: Update version, commit, tag, push
246+
5. **Release Phase**: GitHub Actions auto publish
247+
248+
## Important Notes
249+
250+
- Ensure all code has been tested
251+
- CHANGELOG must follow bilingual format standards
252+
- Choose the correct version type
253+
- Carefully review CHANGELOG content before release
254+
255+
---
256+
257+
**Now starting release process...**

‎.claude/plan/technical-guides-implementation.md‎

Lines changed: 34 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,34 @@
1+
# Technical Guides Implementation Plan
2+
3+
## 背景
4+
5+
用户反馈了两个具体问题：
6+
1. Windows环境下Claude Code经常忘记用双引号包裹路径，导致反斜杠被吞掉
7+
2. 在大型代码库中使用grep搜索容易超时，建议优先使用rg (ripgrep)
8+
9+
## 解决方案
10+
11+
创建独立的 `technical-guides.md` 文件，包含命令执行和工具使用的技术指导。
12+
13+
### 方案选择理由
14+
- 保持模块化设计，与现有的 personality.md、mcp.md 等文件结构一致
15+
- 遵循单一职责原则，rules.md 专注于高层编程原则
16+
- 便于未来扩展更多技术指导
17+
18+
## 实施步骤
19+
20+
1. 创建中英文版本的 technical-guides.md
21+
2. 更新 CLAUDE.md 模板引用新文件
22+
3. 记录实施计划
23+
4. 验证实施效果
24+
25+
## 文件结构
26+
27+
```
28+
templates/
29+
├── CLAUDE.md (更新引用)
30+
├── zh-CN/
31+
│ └── technical-guides.md (新建)
32+
└── en/
33+
└── technical-guides.md (新建)
34+
```

‎templates/CLAUDE.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,5 @@
11
@language.md
22
@personality.md
33
@rules.md
4+
@technical-guides.md
45
@mcp.md

‎templates/en/technical-guides.md‎

Lines changed: 74 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,74 @@
1+
# Technical Execution Guidelines
2+
3+
This document provides best practices that Claude Code should follow when executing specific technical tasks.
4+
5+
## Command Execution Best Practices
6+
7+
### Path Handling Standards
8+
9+
**Important**: Always use double quotes to wrap file paths when executing commands on all operating systems, especially on Windows.
10+
11+
#### Correct Examples
12+
```bash
13+
# ✅ Correct: Paths wrapped in double quotes
14+
cd "C:\Users\name\My Documents"
15+
python "C:\Program Files\MyApp\script.py"
16+
node "/path/with spaces/app.js"
17+
```
18+
19+
#### Incorrect Examples
20+
```bash
21+
# ❌ Incorrect: No quotes, backslashes will be swallowed on Windows
22+
cd C:\Users\name\My Documents
23+
python C:\Program Files\MyApp\script.py
24+
```
25+
26+
### Cross-Platform Compatibility
27+
28+
- Prefer forward slashes `/` as path separators (supported by most tools)
29+
- When backslashes must be used, ensure paths are wrapped in double quotes
30+
- Be mindful of spaces and special characters even with relative paths
31+
32+
## Search Tool Usage Guidelines
33+
34+
### Content Search Priority
35+
36+
**Always prioritize `rg` (ripgrep) for file content searches** over `grep`.
37+
38+
> **Note**: ripgrep requires user installation. Most developers already have this tool installed. If `rg` command is not found, remind users to install:
39+
> - macOS: `brew install ripgrep`
40+
> - Windows: `scoop install ripgrep` or `choco install ripgrep`
41+
> - Linux: `sudo apt-get install ripgrep` or see [official installation guide](https://github.com/BurntSushi/ripgrep#installation)
42+
43+
#### Reasons
44+
1. **Superior Performance**: rg won't timeout in large codebases (e.g., Chromium, Emacs)
45+
2. **Faster Execution**: rg is significantly faster than grep
46+
3. **Smarter Defaults**: Automatically respects .gitignore files
47+
48+
#### Usage Examples
49+
```bash
50+
# ✅ Prefer rg
51+
rg "search pattern" .
52+
rg -i "case insensitive" src/
53+
rg -t js "console.log" .
54+
55+
# ⚠️ Only use grep when rg is unavailable
56+
grep -r "pattern" .
57+
```
58+
59+
### File Finding
60+
- Use Glob tool for filename pattern matching
61+
- Use LS tool for directory listings
62+
- Avoid using `find` command (specialized tools are more efficient)
63+
64+
## Tool Usage Principles
65+
66+
1. **Prefer Specialized Tools**: Use Read, Write, Edit tools instead of cat, echo commands
67+
2. **Batch Operations**: Call multiple tools simultaneously for efficiency
68+
3. **Error Handling**: Check for path quoting issues first when commands fail
69+
70+
## Performance Optimization Tips
71+
72+
- Use Task tool for complex searches in large projects
73+
- Understand project structure before searching to narrow scope
74+
- Use search parameters wisely (e.g., file type filters) for efficiency

0 commit comments

Comments
 (0)