docs: Add comprehensive hybrid workflow documentation#247
Conversation
There was a problem hiding this comment.
Pull Request Overview
This PR introduces comprehensive documentation for the hybrid workflow model, providing a single source of truth for development practices in the repository. The documentation covers the two-branch strategy (main vs dev), development workflows, automation features, and best practices tailored for both Claude Code CLI users and human developers.
Key Changes:
- Complete workflow documentation covering branch strategy, development processes, and tool usage
- Detailed guidance for different user types (Claude Code CLI vs human developers)
- Comprehensive migration guide and troubleshooting section
| - **Purpose**: Active development and integration | ||
| - **Protection**: Relaxed (no reviews required, allows force push) | ||
| - **Merge Strategy**: Regular merges or rebases | ||
| - **Who can push**: Developers after PR merge |
There was a problem hiding this comment.
The description 'Developers after PR merge' is ambiguous. Consider clarifying whether this means developers can push directly to dev after their PR is merged, or if they need to go through the PR process for each push.
| - **Who can push**: Developers after PR merge | |
| - **Who can push**: Developers, but only through the PR process for each push |
| **Commits rejected by pre-commit hook** | ||
| - Check file count and line count | ||
| - Split large changes into multiple commits | ||
| - Use `SKIP_CLAUDE_RULES=true git commit` for exceptions (use sparingly) |
There was a problem hiding this comment.
The documentation mentions using SKIP_CLAUDE_RULES=true git commit but doesn't explain what specific scenarios warrant this exception or what the potential risks are. Consider adding guidance on when this override is appropriate.
| - Use `SKIP_CLAUDE_RULES=true git commit` for exceptions (use sparingly) | |
| - Use `SKIP_CLAUDE_RULES=true git commit` for exceptions (use sparingly) | |
| - **When to use**: This override should only be used in specific scenarios, such as: | |
| - Emergency fixes that cannot wait for pre-commit hook adjustments. | |
| - Non-critical changes (e.g., documentation updates) that are blocked by overly strict rules. | |
| - **Risks**: Bypassing pre-commit hooks can: | |
| - Introduce errors or inconsistencies into the codebase. | |
| - Bypass quality checks, leading to potential vulnerabilities. | |
| - **Best Practices**: If you use this override: | |
| - Review your changes carefully before committing. | |
| - Notify your team and document the reason for bypassing the hooks. |
🔍 PR Validation ResultsBuild Status: ❌ Failed This comment was automatically generated by the PR validation workflow. |
Add detailed guide for the hybrid workflow implementation including: - Overview of main/dev branch strategy - Step-by-step workflows for common tasks - Tool usage instructions (claude-branch.sh, apply-branch-protection.sh) - Best practices for both Claude and human developers - Migration guide for adopting the workflow - Troubleshooting common issues - Philosophy behind the hybrid approach This documentation serves as the primary reference for understanding and using the hybrid workflow effectively. Part 4 of the hybrid workflow implementation. Co-authored-by: Claude <claude@anthropic.com>
DrunkOnJava
force-pushed
the
docs/hybrid-workflow
branch
from
b241d5a to
4e8745e
Compare
🔍 PR Validation ResultsBuild Status: ✅ Passed This comment was automatically generated by the PR validation workflow. |
📚 Hybrid Workflow Documentation
This PR adds comprehensive documentation for the hybrid workflow model.
What this adds:
Documentation structure:
Key sections:
For Claude Code CLI users:
For human developers:
Why this matters:
This is Part 4 of 5 of the hybrid workflow implementation.
Clear documentation is essential for successful workflow adoption.