Skip to content

CLAUDE.md

Latest commit

 

History

History
212 lines (145 loc) · 7.32 KB

CLAUDE.md

File metadata and controls

212 lines (145 loc) · 7.32 KB
Raw

HASH Development Guide

Critical Thinking and Feedback

IMPORTANT: Always critically evaluate and challenge user suggestions, even when they seem reasonable.

USE BRUTAL HONESTY: Don't try to be polite or agreeable. Be direct, challenge assumptions, and point out flaws immediately.

  • Question assumptions: Don't just agree - analyze if there are better approaches
  • Offer alternative perspectives: Suggest different solutions or point out potential issues
  • Challenge organization decisions: If something doesn't fit logically, speak up
  • Point out inconsistencies: Help catch logical errors or misplaced components
  • Research thoroughly: Never skim documentation or issues - read them completely before responding
  • Use proper tools: For GitHub issues, always use gh cli instead of WebFetch (WebFetch may miss critical content)
  • Admit ignorance: Say "I don't know" instead of guessing or agreeing without understanding

This critical feedback helps improve decision-making and ensures robust solutions. Being agreeable is less valuable than being thoughtful and analytical.

Example Behaviors

  • ✅ "I disagree - that component belongs in a different file because..."
  • ✅ "Have you considered this alternative approach?"
  • ✅ "This seems inconsistent with the pattern we established..."
  • ❌ Just implementing suggestions without evaluation

Repository Structure and Navigation

The HASH repository is organized into several key directories:

  • /apps - Core applications powering HASH

    • /hash-api - Backend API service
    • /hash-frontend - Web frontend application
    • /hash-graph - Graph database service
    • /hash-external-services - External service integrations
    • /hash-ai-worker-ts - AI worker services
    • /hash-integration-worker - Integration worker services

  • /blocks - Block Protocol components (each subfolder contains a self-contained block)

  • /libs - Shared libraries and packages

    • /@blockprotocol - Block Protocol related libraries
    • /@hashintel - HASH-specific libraries
    • /@local - Internal libraries for the monorepo
    • Other core libraries (e.g., error-stack)

  • /infra - Deployment and infrastructure code

    • /docker - Docker configurations
    • /terraform - Terraform infrastructure as code

  • /tests - Test suites spanning multiple components

Navigation Tips:

  • When exploring a new feature, first identify which app or lib it belongs to
  • Related code is typically co-located within the same directory
  • Check existing implementations before creating new ones
  • For understanding cross-component interactions, look for integration tests in /tests

Creating Code Context in Rust

To get an idea about an API in rust, the easiest way is to generate it's documentation:

# Generate documentation without opening it
cargo doc --no-deps --all-features --package <package-name>

# Generate documentation for the entire workspace
cargo doc --no-deps --all-features --workspace

These commands will generate HTML documentation from the code and docstrings, providing a comprehensive view of the crate's structure, public API, and usage examples. This approach is particularly effective for:

  1. Understanding a crate's organization and component relationships
  2. Exploring available functions, types, and traits
  3. Finding usage examples in doctest code blocks
  4. Understanding error conditions and handling
  5. Generating test data based on documented structures

Branch Naming Convention

IMPORTANT: Branch names should always include the Linear ticket number.

When creating branches for Linear issues, use the format:

  • <shortname>/h-XXXX-description

Examples:

  • t/h-4892-support-baseurl-and-version-filter
  • alice/h-1234-add-user-authentication
  • bob/h-5678-resolve-database-connection-issue

This ensures traceability between code changes and Linear issues, making it easier to:

  • Track progress on specific tickets
  • Link PRs to their corresponding issues
  • Maintain a clear development history

Pull Request Template

IMPORTANT: PR titles should start with the Linear issue number in format H-XXXX: Description

When creating PRs, use the template located at .github/pull_request_template.md. This template ensures consistency and includes all necessary sections:

  • Purpose and high-level explanation
  • Related links (Linear issues, discussions, etc.)
  • Detailed changes and implementation notes
  • Pre-merge checklist for publishable libraries
  • Documentation and Turbo Graph impact assessment
  • Testing coverage and manual testing steps

Examples of proper PR titles:

  • H-4922: Add branch naming and PR template instructions to CLAUDE.md
  • H-1234: Implement user authentication system
  • H-5678: Fix database connection timeout issue

The template helps reviewers understand the context and ensures all important aspects are covered before merging.

Common Commands

Development

  • Main development: yarn dev (starts API and frontend)
  • Backend only: yarn dev:backend or yarn dev:backend:api
  • Frontend only: yarn dev:frontend

Starting Services

  • Start all services: yarn start
  • Start graph only: yarn start:graph
  • Start backend only: yarn start:backend
  • Start frontend only: yarn start:frontend
  • Start workers: yarn start:worker

Testing

  • Unit tests: yarn test:unit
  • Integration tests: yarn test:integration

Linting and Fixing

  • Lint everything: yarn lint

  • TypeScript type check: yarn lint:tsc

  • ESLint: yarn lint:eslint

  • Formatting check: yarn lint:format

  • Fix ESLint issues: yarn fix:eslint

  • Fix formatting: yarn fix:format

For Specific Packages

When working on a specific package, use:

# For TypeScript/JavaScript packages
turbo run <command> --filter '<package-name>'

# For Rust packages
cargo nextest run --package <package-name>
cargo test --package <package-name> --doc  # For doc tests
cargo clippy --all-features --package <package-name>

For Rust packages, you can add features as needed with --all-features, specific features like --features=foo,bar, or use cargo-hack with --feature-powerset for comprehensive feature testing.

PR Review Guide

When reviewing a Pull Request, follow these steps to provide comprehensive feedback:

1. Initial Information Gathering

Always collect the following information first:

  • PR content (description, title, etc.)
  • Diff changes (show ALL the changes – don't pipe them into head. Don't use --name-only)
  • Existing comments and conversation

Use the following commands:

1a. View PR metadata, description, general comments and changed files

gh pr view <PR_NUMBER> --comments
gh pr diff <PR_NUMBER>

1b. View comments on the diff

gh api \
  -H "Accept: application/vnd.github+json" \
  -H "X-GitHub-Api-Version: 2022-11-28" \
  /repos/OWNER/REPO/pulls/PULL_NUMBER/comments

2. Check Referenced Linear Issues

  • Look for Linear issue references in the PR title or description (format: H-XXXX)
  • Fetch each referenced Linear issue to understand the original requirements
  • Use these requirements as the baseline for your review
# Example of fetching a Linear issue
mcp__linear__get_issue --issueId "H-XXXX"

3. Provide Code Quality Feedback

  • Be precise about the location and nature of issues
  • Include suggestions for improvement when possible
  • Reference relevant code standards from the repository