Skip to content

docs: add rebuild guidance and ICE troubleshooting to AGENTS.md #88337

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
lukesandberg merged 3 commits into from
Jan 12, 2026
+19 −3
Merged

docs: add rebuild guidance and ICE troubleshooting to AGENTS.md #88337

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
ea82abc
docs: add rebuild guidance and ICE troubleshooting to AGENTS.md
lukesandberg Jan 9, 2026
355b504
emphasize graphite instructions
lukesandberg Jan 9, 2026
9300306
Update AGENTS.md
lukesandberg Jan 9, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
22 changes: 19 additions & 3 deletions AGENTS.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -41,13 +41,20 @@ The main Next.js framework lives in `packages/next/`. This is what gets publishe

## Git Workflow

**Use Graphite for all git operations** instead of raw git commands:
**CRITICAL: Use Graphite (`gt`) instead of git for ALL branch and commit operations.**

NEVER use these git commands directly:

- `git push` → use `gt submit --no-edit`
- `git branch` → use `gt create`

**Graphite commands:**

- `gt create <branch-name> -m "message"` - Create a new branch with commit
- `gt modify -a --no-edit` - Stage all and amend current branch's commit
- `gt checkout <branch>` - Switch branches (use instead of `git checkout`)
- `gt checkout <branch>` - Switch branches
- `gt sync` - Sync and restack all branches
- `gt submit --no-edit` - Push and create/update PRs (use `--no-edit` to avoid interactive prompts)
- `gt submit --no-edit` - Push and create/update PRs
- `gt log short` - View stack status

**Note**: `gt submit` runs in interactive mode by default and won't push in automated contexts. Always use `gt submit --no-edit` or `gt submit -q` when running from Claude.
Expand Down Expand Up @@ -295,6 +302,14 @@ See [Codebase structure](#codebase-structure) above for detailed explanations.
- Keep commit messages concise and descriptive
- PR descriptions should focus on what changed and why

## Rebuilding Before Running Tests

When running Next.js integration tests, you must rebuild if source files have changed:

- **Edited Next.js code?** → `pnpm build`
- **Edited Turbopack (Rust)?** → `pnpm swc-build-native`
- **Edited both?** → `pnpm turbo build build-native`

## Development Anti-Patterns

### Test Gotchas
Expand All @@ -305,6 +320,7 @@ See [Codebase structure](#codebase-structure) above for detailed explanations.
### Rust/Cargo

- cargo fmt uses ASCII order (uppercase before lowercase) - just run `cargo fmt`
- **Internal compiler error (ICE)?** Delete incremental compilation artifacts and retry. Remove `*/incremental` directories from your cargo target directory (default `target/`, or check `CARGO_TARGET_DIR` env var)

### Node.js Source Maps

Expand Down
Loading