Skip to content

Commit 3cbad3d

Browse files
platinummonkeyplatinummonkey
committed
update CLAUDE.md
1 parent 92485e1 commit 3cbad3d

1 file changed

Lines changed: 222 additions & 2 deletions

File tree

‎CLAUDE.md‎

Lines changed: 222 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -286,6 +286,17 @@ fetch/
286286

287287
## Development Guidelines
288288

289+
### Workflow for Claude Code
290+
291+
**When completing any task that involves code changes:**
292+
1. Create a feature branch with appropriate prefix (feat/, fix/, etc.)
293+
2. Make changes following the code style guidelines below
294+
3. Stage specific files (avoid `git add .`)
295+
4. Commit with conventional commit format
296+
5. Create PR using `gh pr create` with detailed description
297+
298+
See the [Automated Development Workflow](#automated-development-workflow-for-claude-code) section for complete details and examples.
299+
289300
### Code Style
290301

291302
- Follow standard Go conventions and idioms
@@ -371,7 +382,216 @@ Based on the TypeScript plugin implementation:
371382
go run main.go <command>
372383
```
373384

374-
### Pull Request Process
385+
### Automated Development Workflow (For Claude Code)
386+
387+
When working on tasks, follow this automated workflow:
388+
389+
#### 1. Create Feature Branch
390+
391+
Create a descriptive branch name based on the work being done:
392+
393+
```bash
394+
# Branch naming convention: <type>/<short-description>
395+
# Examples:
396+
git checkout -b feat/oauth2-token-refresh
397+
git checkout -b fix/metrics-query-timeout
398+
git checkout -b refactor/simplify-auth-client
399+
git checkout -b docs/update-readme-oauth
400+
```
401+
402+
**Branch type prefixes:**
403+
- `feat/` - New features
404+
- `fix/` - Bug fixes
405+
- `refactor/` - Code refactoring
406+
- `docs/` - Documentation updates
407+
- `test/` - Test additions/updates
408+
- `chore/` - Maintenance tasks
409+
- `perf/` - Performance improvements
410+
411+
#### 2. Make Changes and Commit
412+
413+
After completing the work:
414+
415+
1. **Stage relevant files** (prefer specific files over `git add .`):
416+
```bash
417+
git add pkg/auth/oauth/client.go pkg/auth/oauth/client_test.go
418+
```
419+
420+
2. **Commit with conventional commit message**:
421+
```bash
422+
git commit -m "$(cat <<'EOF'
423+
<type>(<scope>): <subject>
424+
425+
<body describing what changed and why>
426+
427+
- Key change 1
428+
- Key change 2
429+
- Key change 3
430+
431+
Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
432+
EOF
433+
)"
434+
```
435+
436+
**Important**: Always include the Co-Authored-By line to credit Claude's contribution.
437+
438+
#### 3. Create Pull Request with gh CLI
439+
440+
Use `gh` CLI to push and create PR in one step:
441+
442+
```bash
443+
gh pr create \
444+
--title "<type>(<scope>): <clear, concise title>" \
445+
--body "$(cat <<'EOF'
446+
## Summary
447+
Brief overview of what this PR does (1-2 sentences).
448+
449+
## Changes
450+
- Specific change 1 with file reference
451+
- Specific change 2 with file reference
452+
- Specific change 3 with file reference
453+
454+
## Testing
455+
- Test scenarios covered
456+
- How to verify the changes
457+
458+
## Related Issues
459+
Closes #<issue-number> (if applicable)
460+
Fixes #<issue-number> (if applicable)
461+
462+
---
463+
🤖 Generated with [Claude Code](https://claude.com/claude-code)
464+
EOF
465+
)" \
466+
--label "<appropriate-labels>" \
467+
--draft # Optional: use --draft for work-in-progress
468+
469+
# Example:
470+
gh pr create \
471+
--title "feat(auth): implement OAuth2 token refresh with PKCE" \
472+
--body "$(cat <<'EOF'
473+
## Summary
474+
Implements automatic OAuth2 token refresh using PKCE flow to maintain authentication without user intervention.
475+
476+
## Changes
477+
- Added token refresher in pkg/auth/refresh/refresher.go:45
478+
- Implemented background refresh scheduler
479+
- Added unit tests for refresh logic in pkg/auth/refresh/refresher_test.go
480+
- Updated OAuth client to use refresh tokens
481+
482+
## Testing
483+
- Unit tests verify refresh token exchange
484+
- Integration tests validate automatic refresh before expiration
485+
- Manual test: wait 50 minutes and verify token auto-refreshes
486+
487+
## Related Issues
488+
Closes #42
489+
490+
---
491+
🤖 Generated with [Claude Code](https://claude.com/claude-code)
492+
EOF
493+
)" \
494+
--label "enhancement,auth"
495+
```
496+
497+
#### 4. PR Description Best Practices
498+
499+
**Good PR descriptions include:**
500+
- **Summary**: What and why in 1-2 sentences
501+
- **Changes**: Bulleted list of specific changes with file references
502+
- **Testing**: How the changes were tested
503+
- **Related Issues**: Link to GitHub issues using `Closes #N` or `Fixes #N`
504+
- **Screenshots/Examples**: For UI changes or CLI output changes
505+
- **Breaking Changes**: Clearly marked if any
506+
- **Migration Guide**: If breaking changes require user action
507+
508+
**Example of excellent PR body:**
509+
```markdown
510+
## Summary
511+
Adds OAuth2 authentication with PKCE to replace API key authentication, providing better security and per-installation access control.
512+
513+
## Changes
514+
- Implemented DCR client in pkg/auth/dcr/client.go
515+
- Added PKCE challenge generation in pkg/auth/oauth/pkce.go:23
516+
- Integrated OS keychain storage in pkg/auth/storage/keychain.go
517+
- Added `pup auth login` command in cmd/auth.go:156
518+
- Updated CLAUDE.md with OAuth2 documentation
519+
520+
## Testing
521+
- Unit tests cover all OAuth2 flow steps
522+
- Integration tests validate end-to-end authentication
523+
- Manual testing on macOS, Linux, and Windows
524+
- Verified keychain storage and fallback to encrypted file
525+
526+
## Breaking Changes
527+
None. OAuth2 is opt-in; API key authentication still works.
528+
529+
## Related Issues
530+
Closes #42
531+
Implements RFC: #38
532+
533+
---
534+
🤖 Generated with [Claude Code](https://claude.com/claude-code)
535+
```
536+
537+
#### 5. Complete Automated Workflow Example
538+
539+
Here's the complete workflow in one script:
540+
541+
```bash
542+
# 1. Create feature branch
543+
git checkout -b feat/add-oauth2-auth
544+
545+
# 2. [Make code changes...]
546+
547+
# 3. Stage specific files
548+
git add pkg/auth/oauth/ cmd/auth.go
549+
550+
# 4. Commit with proper message
551+
git commit -m "$(cat <<'EOF'
552+
feat(auth): add OAuth2 authentication with PKCE
553+
554+
Implement OAuth2 authentication flow including:
555+
- Dynamic Client Registration (DCR)
556+
- PKCE code challenge generation
557+
- Secure token storage via OS keychain
558+
- Automatic token refresh
559+
560+
Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
561+
EOF
562+
)"
563+
564+
# 5. Create PR with gh CLI
565+
gh pr create \
566+
--title "feat(auth): add OAuth2 authentication with PKCE" \
567+
--body "$(cat <<'EOF'
568+
## Summary
569+
Adds OAuth2 authentication with PKCE flow to provide secure, per-installation authentication as an alternative to API keys.
570+
571+
## Changes
572+
- Implemented DCR client in pkg/auth/dcr/client.go
573+
- Added PKCE utilities in pkg/auth/oauth/pkce.go
574+
- Created token storage with keychain integration
575+
- Added `pup auth login/logout/status` commands
576+
- Updated documentation in CLAUDE.md
577+
578+
## Testing
579+
- Unit tests for OAuth flow components
580+
- Integration tests for end-to-end flow
581+
- Manual testing on macOS/Linux/Windows
582+
- Verified token refresh automation
583+
584+
## Related Issues
585+
Closes #42
586+
587+
---
588+
🤖 Generated with [Claude Code](https://claude.com/claude-code)
589+
EOF
590+
)" \
591+
--label "enhancement,auth"
592+
```
593+
594+
### Pull Request Process (For Human Contributors)
375595

376596
1. **Create a feature branch**: `git checkout -b feature/your-feature-name`
377597
2. **Make your changes**: Write clear, well-documented code
@@ -380,7 +600,7 @@ Based on the TypeScript plugin implementation:
380600
5. **Run linters**: `golangci-lint run`
381601
6. **Commit changes**: Use clear, descriptive commit messages
382602
7. **Push branch**: `git push origin feature/your-feature-name`
383-
8. **Create PR**: Open a pull request with detailed description
603+
8. **Create PR**: Open a pull request with detailed description (use `gh pr create` or web UI)
384604
9. **Address feedback**: Respond to review comments promptly
385605
10. **Merge**: Once approved, squash and merge
386606

0 commit comments

Comments
 (0)