Skip to content

Commit b5c0097

Browse files
jackiotyujackiotyu
committed
docs: update AGENTS.md with enhanced development guidelines and project structure
1 parent 0989519 commit b5c0097

1 file changed

Lines changed: 159 additions & 133 deletions

File tree

‎AGENTS.md‎

Lines changed: 159 additions & 133 deletions
Original file line numberDiff line numberDiff line change
@@ -1,133 +1,159 @@
1-
# AGENTS.md
2-
3-
## AI Agent Development Guide
4-
5-
This document provides guidance for AI agents (such as Kiro, Claude, ChatGPT, etc.) when developing the Git Worktree Manager extension.
6-
7-
### Project Overview
8-
9-
Git Worktree Manager is a VSCode extension designed to simplify Git worktree management. It allows developers to work on different branches of the same repository in parallel without frequently switching branches or dealing with stash operations.
10-
11-
### Core Features
12-
13-
- **Worktree Management**: Create, delete, and switch Git worktrees
14-
- **Workspace Integration**: Add worktrees to VSCode workspace
15-
- **Favorites System**: Save frequently used worktrees for quick access
16-
- **Multi-language Support**: Supports English, Simplified Chinese, Traditional Chinese, and Japanese
17-
- **Terminal Integration**: Open terminals in specified directories
18-
- **Branch Management**: Create worktrees from branches, switch branches, etc.
19-
20-
### Tech Stack
21-
22-
- **Language**: TypeScript
23-
- **Framework**: VSCode Extension API
24-
- **Build Tool**: Rspack
25-
- **Package Manager**: pnpm
26-
- **Internationalization**: VSCode l10n
27-
28-
### Project Structure
29-
30-
```
31-
├── src/
32-
│ ├── core/ # Core functionality modules
33-
│ ├── constants.ts # Constants definition
34-
│ ├── extension.ts # Extension entry point
35-
│ └── types.ts # Type definitions
36-
├── l10n/ # Internationalization files
37-
├── images/ # Icons and demo videos
38-
├── package.json # Extension configuration and command definitions
39-
└── dist/ # Build output
40-
```
41-
42-
### Development Guidelines
43-
44-
#### 1. Code Style
45-
- Use TypeScript strict mode
46-
- Follow ESLint and Prettier configurations
47-
- Use meaningful variable and function names
48-
- Add appropriate comments, especially for complex Git operations
49-
50-
#### 2. VSCode Extension Best Practices
51-
- Use `vscode.commands.registerCommand` to register commands
52-
- Define UI elements through the `contributes` section in `package.json`
53-
- Use TreeDataProvider to implement tree views
54-
- Handle async operations and errors properly
55-
56-
#### 3. Git Operations
57-
- Use `child_process` to execute Git commands
58-
- Always check Git command exit codes
59-
- Provide meaningful error messages
60-
- Support path handling for different operating systems
61-
62-
#### 4. Internationalization
63-
- All user-visible strings should be internationalized
64-
- Use `vscode.l10n.t()` for translations
65-
- Maintain translation files in the `l10n/` directory
66-
67-
#### 5. Configuration Management
68-
- Read configuration through `vscode.workspace.getConfiguration()`
69-
- Define configuration items in `package.json`
70-
- Provide reasonable default values
71-
72-
### Common Development Tasks
73-
74-
#### Adding New Commands
75-
1. Define the command in `package.json` under `contributes.commands`
76-
2. Implement command logic in the appropriate module
77-
3. Register the command in `extension.ts` or related modules
78-
4. Add necessary internationalization strings
79-
80-
#### Modifying UI Elements
81-
1. Update the `contributes` configuration in `package.json`
82-
2. Modify the corresponding TreeDataProvider or WebView
83-
3. Update related icons and styles
84-
85-
#### Adding Configuration Items
86-
1. Define in `package.json` under `contributes.configuration`
87-
2. Read using `vscode.workspace.getConfiguration()` in code
88-
3. Add internationalization strings for configuration descriptions
89-
90-
### Testing Guidelines
91-
92-
- Test on different operating systems (Windows, macOS, Linux)
93-
- Test various Git repository states (clean, with uncommitted changes, etc.)
94-
- Verify correct display of internationalized strings
95-
- Test error handling and edge cases
96-
97-
### Debugging Tips
98-
99-
- Use VSCode's Extension Development Host for debugging
100-
- Check extension logs in the "Output" panel
101-
- Use `console.log` or `logger.log` for debug output
102-
- Examine Git command output and error messages
103-
104-
### Release Process
105-
106-
1. Update version number (`package.json`)
107-
2. Update `CHANGELOG.md`
108-
3. Run tests to ensure functionality
109-
4. Build extension package: `vsce package`
110-
5. Publish to VSCode Marketplace
111-
112-
### Contribution Guidelines
113-
114-
- Follow existing code style and architecture
115-
- Add appropriate tests for new features
116-
- Update relevant documentation
117-
- Ensure backward compatibility
118-
- Provide clear PR descriptions
119-
120-
### Useful Resources
121-
122-
- [VSCode Extension API](https://code.visualstudio.com/api)
123-
- [Git Worktree Documentation](https://git-scm.com/docs/git-worktree)
124-
- [VSCode Internationalization Guide](https://code.visualstudio.com/api/pluginapis/localization)
125-
- [Project GitHub Repository](https://github.com/jackiotyu/git-worktree-manager)
126-
127-
### Important Notes
128-
129-
- Always consider cross-platform compatibility
130-
- Handle cases where Git repository doesn't exist or is corrupted
131-
- Provide user-friendly error messages
132-
- Maintain extension performance and responsiveness
133-
- Follow VSCode UX guidelines
1+
# AGENTS.md
2+
3+
## AI Agent Development Guide
4+
5+
This document provides guidance for AI agents (such as Kiro, Claude, ChatGPT, etc.) when developing the Git Worktree Manager extension.
6+
7+
### Project Overview
8+
9+
Git Worktree Manager is a VSCode extension designed to simplify Git worktree management. It allows developers to work on different branches of the same repository in parallel without frequently switching branches or dealing with stash operations.
10+
11+
### Core Features
12+
13+
- **Worktree Management**: Create, delete, and switch Git worktrees
14+
- **Workspace Integration**: Add worktrees to VSCode workspace
15+
- **Favorites System**: Save frequently used worktrees for quick access
16+
- **Multi-language Support**: Supports English, Simplified Chinese, Traditional Chinese, and Japanese
17+
- **Terminal Integration**: Open terminals in specified directories
18+
- **Branch Management**: Create worktrees from branches, switch branches, etc.
19+
20+
### Tech Stack
21+
22+
- **Language**: TypeScript
23+
- **Framework**: VSCode Extension API
24+
- **Build Tool**: Rspack
25+
- **Package Manager**: pnpm
26+
- **Internationalization**: VSCode l10n
27+
28+
### Project Structure
29+
30+
```
31+
├── src/
32+
│ ├── core/ # Core functionality modules
33+
│ │ ├── bootstrap.ts # Extension initialization and registration
34+
│ │ ├── folderRoot.ts # Manage root repository folders
35+
│ │ ├── gitHistory.ts # Handle git history visualization
36+
│ │ ├── command/ # Command implementations (each command is a separate file)
37+
│ │ ├── config/ # Configuration management module (use Config class instead of direct vscode.workspace.getConfiguration)
38+
│ │ ├── event/ # Event emitters and handlers
39+
│ │ ├── git/ # Git operations (worktrees, branches, commits, etc.)
40+
│ │ ├── hooks/ # Git hooks management
41+
│ │ ├── log/ # Logging utility
42+
│ │ ├── quickPick/ # QuickPick UI helpers
43+
│ │ ├── state/ # Global and Workspace state management
44+
│ │ ├── treeView/ # Tree view provider implementations
45+
│ │ ├── ui/ # UI components and utilities
46+
│ │ └── util/ # General utilities (file paths, system explorer, etc.)
47+
│ ├── constants.ts # Constants and enum definitions
48+
│ ├── extension.ts # Extension entry point (activate/deactivate)
49+
│ ├── types.ts # TypeScript type definitions
50+
│ └── @types/ # Custom type definitions for vscode.git API
51+
├── l10n/ # Internationalization files
52+
├── images/ # Icons and demo videos
53+
├── package.json # Extension manifest and command definitions
54+
├── pnpm-workspace.yaml # Workspace configuration
55+
├── rspack.config.js # Build configuration
56+
└── dist/ # Build output
57+
```
58+
59+
### Development Guidelines
60+
61+
#### 1. Code Style
62+
- Use TypeScript strict mode
63+
- Follow ESLint and Prettier configurations
64+
- Use meaningful variable and function names
65+
- Add appropriate comments, especially for complex Git operations
66+
67+
#### 2. Configuration & State Management (IMPORTANT)
68+
- **Configuration Access**: MUST use `Config` class from `@/core/config/setting.ts`, NEVER directly call `vscode.workspace.getConfiguration()`
69+
- ❌ WRONG: `vscode.workspace.getConfiguration('git-worktree-manager').get('key')`
70+
- ✅ CORRECT: `Config.get('key', defaultValue)`
71+
- Benefits: Type-safe, consistent defaults, easier to maintain, single point of change
72+
- **Global State**: Use `GlobalState` from `@/core/state/index.ts` for extension-wide persistent storage
73+
- **Workspace State**: Use `WorkspaceState` from `@/core/state/index.ts` for workspace-specific storage
74+
- All configuration defaults must match the corresponding values defined in `package.json`
75+
76+
#### 4. VSCode Extension Best Practices
77+
- Use `vscode.commands.registerCommand` to register commands
78+
- Define UI elements through the `contributes` section in `package.json`
79+
- Use TreeDataProvider to implement tree views
80+
- Handle async operations and errors properly
81+
82+
#### 5. Git Operations
83+
- Use `child_process` to execute Git commands
84+
- Always check Git command exit codes
85+
- Provide meaningful error messages
86+
- Support path handling for different operating systems
87+
88+
#### 4. Internationalization
89+
- All user-visible strings should be internationalized
90+
- Use `vscode.l10n.t()` for translations
91+
- Maintain translation files in the `l10n/` directory
92+
93+
#### 5. Configuration Management
94+
- Read configuration through `vscode.workspace.getConfiguration()`
95+
- Define configuration items in `package.json`
96+
- Provide reasonable default values
97+
98+
### Common Development Tasks
99+
100+
#### Adding New Commands
101+
1. Define the command in `package.json` under `contributes.commands`
102+
2. Implement command logic in the appropriate module
103+
3. Register the command in `extension.ts` or related modules
104+
4. Add necessary internationalization strings
105+
106+
#### Modifying UI Elements
107+
1. Update the `contributes` configuration in `package.json`
108+
2. Modify the corresponding TreeDataProvider or WebView
109+
3. Update related icons and styles
110+
111+
#### Adding Configuration Items
112+
1. Define in `package.json` under `contributes.configuration`
113+
2. Read using `vscode.workspace.getConfiguration()` in code
114+
3. Add internationalization strings for configuration descriptions
115+
116+
### Testing Guidelines
117+
118+
- Test on different operating systems (Windows, macOS, Linux)
119+
- Test various Git repository states (clean, with uncommitted changes, etc.)
120+
- Verify correct display of internationalized strings
121+
- Test error handling and edge cases
122+
123+
### Debugging Tips
124+
125+
- Use VSCode's Extension Development Host for debugging
126+
- Check extension logs in the "Output" panel
127+
- Use `console.log` or `logger.log` for debug output
128+
- Examine Git command output and error messages
129+
130+
### Release Process
131+
132+
1. Update version number (`package.json`)
133+
2. Update `CHANGELOG.md`
134+
3. Run tests to ensure functionality
135+
4. Build extension package: `vsce package`
136+
5. Publish to VSCode Marketplace
137+
138+
### Contribution Guidelines
139+
140+
- Follow existing code style and architecture
141+
- Add appropriate tests for new features
142+
- Update relevant documentation
143+
- Ensure backward compatibility
144+
- Provide clear PR descriptions
145+
146+
### Useful Resources
147+
148+
- [VSCode Extension API](https://code.visualstudio.com/api)
149+
- [Git Worktree Documentation](https://git-scm.com/docs/git-worktree)
150+
- [VSCode Internationalization Guide](https://code.visualstudio.com/api/pluginapis/localization)
151+
- [Project GitHub Repository](https://github.com/jackiotyu/git-worktree-manager)
152+
153+
### Important Notes
154+
155+
- Always consider cross-platform compatibility
156+
- Handle cases where Git repository doesn't exist or is corrupted
157+
- Provide user-friendly error messages
158+
- Maintain extension performance and responsiveness
159+
- Follow VSCode UX guidelines

0 commit comments

Comments
 (0)