🚨 CRITICAL GUIDELINES
🚨 重要指南
Windows File Path Requirements
Windows文件路径要求
MANDATORY: Always Use Backslashes on Windows for File Paths
When using Edit or Write tools on Windows, you MUST use backslashes (
) in file paths, NOT forward slashes (
).
Examples:
- ❌ WRONG:
D:/repos/project/file.tsx
- ✅ CORRECT:
D:\repos\project\file.tsx
This applies to:
- Edit tool file_path parameter
- Write tool file_path parameter
- All file operations on Windows systems
强制要求：在Windows系统中使用文件路径时必须使用反斜杠（）
在Windows系统上使用Edit或Write工具时，文件路径必须使用反斜杠（
），绝对不能使用正斜杠（
）。
示例：
- ❌ 错误写法：
D:/repos/project/file.tsx
- ✅ 正确写法：
D:\repos\project\file.tsx
此要求适用于：
- Edit工具的file_path参数
- Write工具的file_path参数
- Windows系统上的所有文件操作
Documentation Guidelines
文档规范
NEVER create new documentation files unless explicitly requested by the user.
- Priority: Update existing README.md files rather than creating new documentation
- Repository cleanliness: Keep repository root clean - only README.md unless user requests otherwise
- Style: Documentation should be concise, direct, and professional - avoid AI-generated tone
- User preference: Only create additional .md files when user specifically asks for documentation
除非用户明确要求，否则绝对不要创建新的文档文件。
- 优先级：优先更新现有README.md文件，而非创建新文档
- 仓库整洁性：保持仓库根目录整洁 - 除非用户要求，否则只保留README.md
- 风格：文档应简洁、直接、专业 - 避免AI生成的冗余语气
- 用户偏好：仅当用户明确要求文档时，才创建额外的.md文件
GitHub AI Features 2025
2025年GitHub AI功能
Trunk-Based Development (TBD)
主干开发（TBD）
Modern workflow used by largest tech companies (Google: 35,000+ developers):
这是大型科技公司（如谷歌：35000+开发者）使用的现代化工作流：
- Short-lived branches: Hours to 1 day maximum
- Small, frequent commits: Reduce merge conflicts
- Continuous integration: Always deployable main branch
- Feature flags: Hide incomplete features
- 短期分支：最长保留几小时到1天
- 小而频繁的提交：减少合并冲突
- 持续集成：主分支始终可部署
- 功能开关：隐藏未完成的功能
Create task branch from main
从主分支创建任务分支
git checkout main
git pull origin main
git checkout -b task/add-login-button
git checkout main
git pull origin main
git checkout -b task/add-login-button
Make small changes
进行小幅度修改
git add src/components/LoginButton.tsx
git commit -m "feat: add login button component"
git add src/components/LoginButton.tsx
git commit -m "feat: add login button component"
Push and create PR (same day)
推送并创建PR（当天完成）
git push origin task/add-login-button
gh pr create --title "Add login button" --body "Implements login UI"
git push origin task/add-login-button
gh pr create --title "Add login button" --body "Implements login UI"
Merge within hours, delete branch
几小时内完成合并，删除分支
gh pr merge --squash --delete-branch
gh pr merge --squash --delete-branch
- Reduced merge conflicts (75% decrease)
- Faster feedback cycles
- Easier code reviews (smaller changes)
- Always releasable main branch
- Simplified CI/CD pipelines
- 合并冲突减少75%
- 反馈周期更短
- 代码评审更简单（修改幅度小）
- 主分支始终可发布
- CI/CD管道更简化
GitHub Secret Protection (AI-Powered)
GitHub AI驱动的密钥保护
AI detects secrets before they reach repository:
Attempt to commit secret
尝试提交密钥
git add config.py
git commit -m "Add config"
git push
git add config.py
git commit -m "Add config"
git push
GitHub AI detects secret:
GitHub AI检测到密钥：
"""
⛔ Push blocked by secret scanning
Found: AWS Access Key
Pattern: AKIA[0-9A-Z]{16}
File: config.py:12
Options:
- Remove secret and try again
- Mark as false positive (requires justification)
- Request review from admin
"""
"""
⛔ 密钥扫描阻止了推送
检测到：AWS访问密钥
匹配模式：AKIA[0-9A-Z]{16}
文件：config.py:12
可选操作：
- 删除密钥后重新尝试
- 标记为误报（需要说明理由）
- 请求管理员审核
"""
Fix: Use environment variables
修复方案：使用环境变量
import os
aws_key = os.environ.get('AWS_ACCESS_KEY')
git add config.py
git commit -m "Use env vars for secrets"
git push # ✅ Success
import os
aws_key = os.environ.get('AWS_ACCESS_KEY')
git add config.py
git commit -m "Use env vars for secrets"
git push # ✅ 推送成功
Supported Secret Types (AI-Enhanced)
AI增强支持的密钥类型
- AWS credentials
- Azure service principals
- Google Cloud keys
- GitHub tokens
- Database connection strings
- API keys (OpenAI, Stripe, etc.)
- Private keys (SSH, TLS)
- OAuth tokens
- Custom patterns (regex-based)
- AWS凭证
- Azure服务主体
- Google Cloud密钥
- GitHub令牌
- 数据库连接字符串
- API密钥（OpenAI、Stripe等）
- 私钥（SSH、TLS）
- OAuth令牌
- 自定义模式（基于正则表达式）
GitHub Code Security
GitHub代码安全
CodeQL Code Scanning
CodeQL代码扫描
AI-powered static analysis:
.github/workflows/codeql.yml
.github/workflows/codeql.yml
name: "CodeQL"
on:
push:
branches: [ main ]
pull_request:
branches: [ main ]
jobs:
analyze:
runs-on: ubuntu-latest
permissions:
security-events: write
steps:
- name: Checkout
uses: actions/checkout@v3
- name: Initialize CodeQL
uses: github/codeql-action/init@v2
with:
languages: javascript, python, java
- name: Autobuild
uses: github/codeql-action/autobuild@v2
- name: Perform CodeQL Analysis
uses: github/codeql-action/analyze@v2
**Detects:**
- SQL injection
- XSS vulnerabilities
- Path traversal
- Command injection
- Insecure deserialization
- Authentication bypass
- Logic errors
name: "CodeQL"
on:
push:
branches: [ main ]
pull_request:
branches: [ main ]
jobs:
analyze:
runs-on: ubuntu-latest
permissions:
security-events: write
steps:
- name: Checkout
uses: actions/checkout@v3
- name: Initialize CodeQL
uses: github/codeql-action/init@v2
with:
languages: javascript, python, java
- name: Autobuild
uses: github/codeql-action/autobuild@v2
- name: Perform CodeQL Analysis
uses: github/codeql-action/analyze@v2
**可检测的问题：**
- SQL注入
- XSS漏洞
- 路径遍历
- 命令注入
- 不安全的反序列化
- 身份验证绕过
- 逻辑错误
Copilot Autofix
Copilot自动修复
AI automatically fixes security vulnerabilities:
Vulnerable code detected by CodeQL
CodeQL检测到的易受攻击代码
def get_user(user_id):
query = f"SELECT * FROM users WHERE id = {user_id}" # ❌ SQL injection
return db.execute(query)
def get_user(user_id):
query = f"SELECT * FROM users WHERE id = {user_id}" # ❌ SQL注入风险
return db.execute(query)
Copilot Autofix suggests:
Copilot自动修复建议：
def get_user(user_id):
query = "SELECT * FROM users WHERE id = ?"
return db.execute(query, (user_id,)) # ✅ Parameterized query
def get_user(user_id):
query = "SELECT * FROM users WHERE id = ?"
return db.execute(query, (user_id,)) # ✅ 参数化查询
One-click to apply fix
一键应用修复
GitHub Agents (Automated Workflows)
GitHub Agents（自动化工作流）
AI agents for automated bug fixes and PR generation:
.github/workflows/ai-bugfix.yml
.github/workflows/ai-bugfix.yml
name: AI Bug Fixer
on:
issues:
types: [labeled]
jobs:
autofix:
if: contains(github.event.issue.labels.*.name, 'bug')
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v3
- name: Analyze Bug
uses: github/ai-agent@v1
with:
task: 'analyze-bug'
issue-number: ${{ github.event.issue.number }}
- name: Generate Fix
uses: github/ai-agent@v1
with:
task: 'generate-fix'
create-pr: true
pr-title: "Fix: ${{ github.event.issue.title }}"
name: AI Bug Fixer
on:
issues:
types: [labeled]
jobs:
autofix:
if: contains(github.event.issue.labels.*.name, 'bug')
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v3
- name: Analyze Bug
uses: github/ai-agent@v1
with:
task: 'analyze-bug'
issue-number: ${{ github.event.issue.number }}
- name: Generate Fix
uses: github/ai-agent@v1
with:
task: 'generate-fix'
create-pr: true
pr-title: "Fix: ${{ github.event.issue.title }}"
Automated PR Generation
自动PR生成
GitHub Agent creates PR automatically
当Issue被标记为"enhancement"时，GitHub Agent会自动创建PR：
When issue is labeled "enhancement":
1. 分析Issue描述
1. Analyzes issue description
2. 生成实现代码
2. Generates implementation code
3. 创建测试用例
3. Creates tests
4. 附带说明打开PR
4. Opens PR with explanation
示例：Issue #42 "添加深色模式切换"
Example: Issue #42 "Add dark mode toggle"
Agent创建的PR包含：
Agent creates PR with:
- DarkModeToggle.tsx组件
- DarkModeToggle.tsx component
- ThemeContext.tsx提供者
- ThemeContext.tsx provider
- 主题切换测试用例
- Tests for theme switching
- 文档更新
Dependency Review (AI-Enhanced)
AI增强的依赖审查
AI analyzes dependency changes in PRs:
.github/workflows/dependency-review.yml
.github/workflows/dependency-review.yml
name: Dependency Review
on: [pull_request]
permissions:
contents: read
jobs:
dependency-review:
runs-on: ubuntu-latest
steps:
- name: Checkout
uses: actions/checkout@v3
- name: Dependency Review
uses: actions/dependency-review-action@v3
with:
fail-on-severity: high
fail-on-scopes: runtime
**AI Insights:**
- Known vulnerabilities in new dependencies
- License compliance issues
- Breaking changes in updates
- Alternative safer packages
- Dependency freshness score
name: Dependency Review
on: [pull_request]
permissions:
contents: read
jobs:
dependency-review:
runs-on: ubuntu-latest
steps:
- name: Checkout
uses: actions/checkout@v3
- name: Dependency Review
uses: actions/dependency-review-action@v3
with:
fail-on-severity: high
fail-on-scopes: runtime
**AI洞察：**
- 新依赖中的已知漏洞
- 许可证合规问题
- 更新中的破坏性变更
- 更安全的替代包
- 依赖新鲜度评分
Trunk-Based Development Workflow
主干开发工作流
Morning: Sync with main
早上：同步主分支
git checkout main
git pull origin main
git checkout main
git pull origin main
git checkout -b task/user-profile-api
git checkout -b task/user-profile-api
Work in small iterations (2-4 hours)
分小迭代工作（2-4小时）
First iteration: API endpoint
第一次迭代：API端点
git add src/api/profile.ts
git commit -m "feat: add profile API endpoint"
git push origin task/user-profile-api
gh pr create --title "Add user profile API" --draft
git add src/api/profile.ts
git commit -m "feat: add profile API endpoint"
git push origin task/user-profile-api
gh pr create --title "Add user profile API" --draft
Continue work: Add tests
继续工作：添加测试用例
git add tests/profile.test.ts
git commit -m "test: add profile API tests"
git push
git add tests/profile.test.ts
git commit -m "test: add profile API tests"
git push
Mark ready for review
标记为可评审状态
Get review (should happen within hours)
等待评审（几小时内完成）
gh pr merge --squash --delete-branch
gh pr merge --squash --delete-branch
Next task: Start fresh from main
下一个任务：从主分支重新开始
git checkout main
git pull origin main
git checkout -b task/profile-ui
git checkout main
git pull origin main
git checkout -b task/profile-ui
Small, Frequent Commits Pattern
小而频繁的提交模式
❌ Bad: Large infrequent commit
❌ 不良实践：大规模的单次提交
git add .
git commit -m "Add complete user profile feature with API, UI, tests, docs"
git add .
git commit -m "Add complete user profile feature with API, UI, tests, docs"
50 files changed, 2000 lines
50个文件变更，2000行代码修改
✅ Good: Small frequent commits
✅ 良好实践：小而频繁的提交
git add src/api/profile.ts
git commit -m "feat: add profile API endpoint"
git push
git add src/components/ProfileCard.tsx
git commit -m "feat: add profile card component"
git push
git add tests/profile.test.ts
git commit -m "test: add profile tests"
git push
git add docs/profile.md
git commit -m "docs: document profile API"
git push
git add src/api/profile.ts
git commit -m "feat: add profile API endpoint"
git push
git add src/components/ProfileCard.tsx
git commit -m "feat: add profile card component"
git push
git add tests/profile.test.ts
git commit -m "test: add profile tests"
git push
git add docs/profile.md
git commit -m "docs: document profile API"
git push
Each commit: 1-3 files, 50-200 lines
每次提交：1-3个文件，50-200行代码修改
Easier reviews, faster merges, less conflicts
评审更简单，合并更快，冲突更少
Security Best Practices (2025)
2025年安全最佳实践
Repository Settings → Security → Secret scanning
仓库设置 → 安全 → 密钥扫描
Enable: Push protection + AI detection
启用：推送保护 + AI检测
2. **Configure CodeQL:**
```bash
Add .github/workflows/codeql.yml
添加 .github/workflows/codeql.yml
Enable for all languages in project
为项目中所有语言启用
3. **Use Copilot Autofix:**
```bash
3. **使用Copilot自动修复：**
```bash
Review security alerts weekly
每周审核安全告警
Apply Copilot-suggested fixes
应用Copilot建议的修复
Test before merging
合并前进行测试
4. **Implement Trunk-Based Development:**
```bash
Branch lifespan: <1 day
分支生命周期：<1天
Commit frequency: Every 2-4 hours
提交频率：每2-4小时一次
Main branch: Always deployable
主分支：始终可部署
5. **Leverage GitHub Agents:**
```bash
5. **利用GitHub Agents：**
```bash
Automate: Bug triage, PR creation, dependency updates
自动化：Bug分类、PR创建、依赖更新
Review: All AI-generated code before merging
合并前审核所有AI生成的代码