Skip to main content

Frequently Asked Questions

Got questions? Check here first! We've gathered the most common questions from new engineers.

Setup & Environment​

See Development Setup for more details.

Q: What's pnpm and why not npm?​

A: pnpm is a faster, more disk-efficient package manager. For this project, use pnpm instead of npm. The main commands are the same:

pnpm install   # instead of npm install
pnpm run build # instead of npm run build

Q: My dev server won't start. What do I do?​

A: Try these steps:

  1. Clear pnpm cache: pnpm store prune
  2. Delete node_modules: rm -rf node_modules pnpm-lock.yaml
  3. Reinstall: pnpm install
  4. Try starting again: pnpm run start

If that doesn't work, ask for help in #engineering on Slack.

Q: I'm on Windows. Will this work?​

A: Yes, but use WSL2 (Windows Subsystem for Linux 2):

  1. Install WSL2: https://docs.microsoft.com/en-us/windows/wsl/install
  2. Install Node.js in WSL2
  3. Clone repository in WSL2
  4. Work from within WSL2

Git & GitLab​

Q: I accidentally committed to main. What do I do?​

A: Don't panic! Here's the fix:

# Undo the commit (keeps your changes)
git reset HEAD~1

# Create a new branch
git checkout -b feature/your-feature-name

# Push the new branch
git push origin feature/your-feature-name

Q: How do I delete a branch?​

A:

# Delete locally
git branch -d feature/branch-name

# Delete remotely
git push origin --delete feature/branch-name

Q: What's the difference between merge and rebase?​

A:

  • Merge: Creates a merge commit, preserves history
  • Rebase: Rewrites history, cleaner but more dangerous if misused

For most cases, use merge. Ask your team lead about rebasing guidelines.

Q: How do I update my branch with latest main?​

A:

# Option 1: Merge main into your branch
git fetch origin
git merge origin/main

# Option 2: Rebase on main
git rebase origin/main

Development & Coding​

Q: How often should I commit?​

A: Commit early and often! A good rule of thumb:

  • Logical units of work (one feature = one commit, ideally)
  • After completing a working test
  • Before trying something risky
  • Keep commits under 400 lines of changes

Q: What if my code review has conflicts?​

A:

  1. Rebase on main: git rebase origin/main
  2. Resolve conflicts in your editor
  3. Continue rebase: git add . && git rebase --continue
  4. Force push: git push origin feature/name --force-with-lease

Q: How long should code review take?​

A:

  • Quick reviews: 1-4 hours
  • Thorough reviews: 1-2 days
  • Complex changes: 2-3 days

Check with your team lead if you're blocked.

Q: What if I disagree with a review comment?​

A:

  1. Reply politely with your reasoning
  2. Ask clarifying questions
  3. Discuss with reviewer
  4. Escalate to team lead if needed

Remember: it's about the code, not the person.

Documentation​

Q: How do I update the documentation?​

A:

  1. Edit .md files in the docs/ folder
  2. Start dev server: pnpm run start
  3. Changes auto-reload at localhost:3000
  4. Commit and push like any other code
  5. Create a merge request

Q: What Markdown features are supported?​

A:

  • Basic markdown syntax
  • Code blocks with language specification
  • Admonitions (note, tip, warning, danger)
  • Tables
  • Links and images
  • HTML (if needed)

See Docusaurus documentation for details.

Q: Where do I add a new documentation page?​

A:

  1. Create a new .md file in the appropriate folder
  2. Add metadata at the top: 
    ---
    sidebar_position: 1
    ---
  3. Update sidebars.js to include the new page
  4. Test locally

Workflow & Process​

Q: What time should I come to work?​

A: Ask your team lead about working hours expectations.

Q: Can I work from home?​

A: Ask your team lead or HR about remote work policies.

Q: How do I request time off?​

A: Contact HR or your team lead with your dates.

Q: What's the code of conduct?​

A: Be respectful, inclusive, and professional. Treat others how you want to be treated.

Troubleshooting​

Q: The site shows a 404 error​

A:

  1. Check the URL path is correct
  2. Clear browser cache (Cmd+Shift+Delete)
  3. Hard refresh (Cmd+Shift+R or Ctrl+Shift+R)
  4. Check the dev console (F12) for errors

Q: My change isn't showing up​

A:

  1. Stop dev server (Ctrl+C)
  2. Start again: pnpm run start
  3. Hard refresh browser
  4. Check file was actually saved

Q: I see a build error​

A:

  1. Read the error message carefully
  2. Check for typos or syntax errors
  3. Verify file paths are correct
  4. Search error message in docs/Stack Overflow
  5. Ask for help if stuck

AI Tooling & MCPs​

Q: Which AI tool should I use?​

A: Choose based on your needs:

  • Claude: Complex analysis, architecture discussions
  • OpenCode: Fast code generation, boilerplate
  • Kiro: Quick suggestions, documentation
  • Cursor: Full IDE replacement with AI

Start with one tool, try others later!

Q: How do I set up MCPs?​

A:

  1. Choose your AI tool
  2. Follow tool-specific setup guide in AI Tooling section
  3. Install recommended MCPs
  4. Configure MCPs for your tool
  5. Test MCP connections
  6. Start using in your workflow

Check MCPs & Configuration for detailed setup.

Q: Are AI suggestions safe to use?​

A: AI is great but not perfect:

  • ✅ Always review AI-generated code
  • ✅ Verify logic and edge cases
  • ✅ Check security implications
  • ✅ Match your team's code style
  • ✅ Add appropriate tests

AI should assist, not replace, code review.

Q: Can I use Claude/OpenCode/Kiro/Cursor together?​

A: Yes! Many engineers use multiple tools:

  • Claude: Deep analysis and discussions
  • OpenCode: Quick code generation
  • Cursor: Continuous coding environment
  • Kiro: Fast inline suggestions

Pick the right tool for the task.

Q: My MCPs aren't connecting​

A:

  1. Verify configuration file syntax (JSON/YAML)
  2. Check file paths are correct
  3. Ensure MCP server has execute permissions
  4. Test MCP independently
  5. Check tool logs for errors
  6. Ask in #engineering if stuck

See MCPs Troubleshooting for details.

Q: Can I share AI tool configuration with my team?​

A: Yes! Best practices:

  1. Create .cursor/config.json or .opencode.json
  2. Commit to repository
  3. Document MCP setup
  4. Share keyboard shortcuts
  5. Discuss team preferences

This ensures everyone uses the same setup.

Q: Which API keys do I need?​

A: It depends on your tool:

  • Claude: Anthropic API key (or subscription)
  • OpenCode: Anthropic or OpenAI API key
  • Kiro: Anthropic API key
  • Cursor: Cursor account (free or paid)

Never commit API keys! Use environment variables.

Q: Can AI help with documentation?​

A: Absolutely! AI tools can:

  • Generate documentation from code
  • Write examples and tutorials
  • Improve existing docs
  • Create API references
  • Suggest documentation improvements

See AI Tooling Guides for more.

Getting More Help​

Can't find your answer?

  • 📖 Check the other documentation sections
  • 💬 Ask in #engineering on Slack
  • 🧑‍💻 Reach out to your onboarding buddy
  • 👨‍💼 Talk to your team lead

Remember: No question is too basic! Everyone started as a new engineer.

Contributing to FAQ​

Found a common question not listed here?

  1. Create a new FAQ item
  2. Submit a merge request
  3. Help the next engineer!

Last Updated: January 2026

Have a question? Add it to this FAQ by editing this file and creating a merge request!