Personal Claude Code Guidelines

CLAUDE.local.md

Pull Request Guidelines

When creating PRs:

1. Create as draft PR (gh pr create --draft)
2. Assign to the user (--assignee @me)
3. Add the "🌟 NEW FEATURE" label (--label "🌟 NEW FEATURE")
4. Do not hard-wrap long Markdown text lines in PR descriptions
5. Do not include Co-Authored-By: Claude line in PR descriptions (co-authorship is already mentioned in commits)

Commit and Push Guidelines

NEVER commit or push changes unless explicitly asked by the user.

When you complete a task:

1. Inform the user what you've done
2. Wait for explicit instruction to commit
3. Only commit when the user says "commit" or similar
4. Only push when the user says "push" or similar

Do not ask "should I commit this?" - just wait for the user's instruction.

Commit Message Guidelines

Wrap commit messages at 72 characters per line for proper display in git tools and terminals.

When adding Claude as a co-author, don’t also add the “Generated with Claude” line to the commit message because it’s implied.

File Format Guidelines

Always ensure files end with a trailing newline (UNIX convention).

Code Formatting Guidelines

Always add a blank line between different block statements (if, try, for, while, etc.) for better readability.

Use underscore as thousand separator for numeric literals (e.g., 10_000 instead of 10000) for better readability.

Always format JS files with Prettier using:

npx prettier --write <file-path>

Ruby Guidelines

Use Ruby shorthand syntax when keys and values have the same name:

• Use { font_family:, font_size: } instead of { font_family: font_family, font_size: font_size }

Place rubocop disable directives inline with the def/class line:

• Use def method_name # rubocop:disable Metrics/MethodLength instead of placing the directive on a separate line above

ActiveRecord Query Optimization

Keep .includes and their usage close together to prevent N+1 queries:

• Prefer inlining code that uses eager-loaded associations rather than extracting to helper methods
• When .includes and the code using those associations are separated, it's easy to accidentally change one without updating the other, leading to N+1 queries
• The proximity makes the dependency between eager loading and association access explicit and obvious

Example (preferred):

def scene_photo_groups
  episodic_scenes
    .includes(episodic_media_attachments: { media_item: :record })
    .filter_map do |scene|
      photos = scene.episodic_media_attachments  # Using the included association
                    .map(&:media_item)
                    .map(&:record)
      # ... rest of code
    end
end

Example (avoid):

def scene_photo_groups
  episodic_scenes
    .includes(episodic_media_attachments: { media_item: :record })
    .filter_map { |scene| build_scene_photo_group(scene) }
end

private

def build_scene_photo_group(scene)
  # Far from the .includes - easy to break accidentally
  photos = scene.episodic_media_attachments.map(&:media_item).map(&:record)
  # ...
end

Rollbar Guidelines (RQL CLI)

Important Notes

• The RQL CLI is located at /Users/vladgurdiga/src/rql/rql.js and can be executed with absolute path

Access Tokens

Each Rollbar project has a corresponding environment variable following the pattern: ROLLBAR_ACCESS_TOKEN_<PROJECT_NAME>

Examples:

• ROLLBAR_ACCESS_TOKEN_EDITOR: For mixbook-html-editor project
• ROLLBAR_ACCESS_TOKEN_UPLOADER: For uploader project

To find the correct token for a project, extract the project name from the Rollbar URL (e.g., mixbook-html-editor from https://app.rollbar.com/a/mixbook/fix/item/mixbook-html-editor/37787) and convert it to the environment variable name by uppercasing and replacing hyphens with underscores.

Query Syntax Notes

• Use item.counter (not item_counter) to reference item counter field
• For counting unique persons, use GROUP BY person.id instead of COUNT(DISTINCT person.id) as the latter may have syntax issues
• Person ID field is accessed as person.id in SELECT and GROUP BY clauses

Rollbar URL to Counter Mapping

When given a Rollbar URL like https://app.rollbar.com/a/mixbook/fix/item/mixbook-html-editor/37787, the last number (37787) is the item counter to use in queries.

Performance Considerations

When writing RQL queries, keep these performance tips in mind (see Rollbar RQL Performance Docs):

• Use specific time ranges instead of querying all data
• Add indexes on frequently queried fields
• Use LIMIT clauses to restrict result sets
• Avoid SELECT * – only query needed fields
• Use aggregations (GROUP BY, COUNT) efficiently
• Filter early with WHERE clauses before joins/aggregations
• Be mindful of large result sets that may timeout

Common Query Templates

Get item details by counter:

/Users/vladgurdiga/src/rql/rql.js -t "$ROLLBAR_ACCESS_TOKEN_EDITOR" "SELECT item.counter, item.title, item.level, item.total_occurrences, item.environment, item.status, item.last_occurrence_timestamp FROM item_occurrence WHERE item.counter = <COUNTER> LIMIT 1"

Get recent occurrences with body details:

/Users/vladgurdiga/src/rql/rql.js -t "$ROLLBAR_ACCESS_TOKEN_UPLOADER" "SELECT body FROM item_occurrence WHERE item.counter = <COUNTER> ORDER BY occurrence.timestamp DESC LIMIT 200"

Correlating Rollbar Errors with SumoLogic

When investigating Rollbar errors, you can correlate them with SumoLogic logs to get additional context (like file sizes, request details, etc.):

1. Get temp filenames from Rollbar: Query RQL for occurrence bodies which contain temp file paths
2. Extract temp filenames: Parse the JSON bodies to find temp file paths (e.g., /tmp/open-uri20241125-7-abc123.heic)
3. Build SumoLogic query: Search for the temp filename in SumoLogic logs
4. Get request_id: Find the log record containing the temp filename and extract its request_id
5. Query for file metadata: Use the request_id to find file size and other metadata

Example workflow:

# Step 1: Get Rollbar occurrences with temp filenames
/Users/vladgurdiga/src/rql/rql.js -t "$ROLLBAR_ACCESS_TOKEN_UPLOADER" "SELECT body FROM item_occurrence WHERE item.counter = 2580 ORDER BY occurrence.timestamp DESC LIMIT 200" > occurrences.json

# Step 2: Extract temp filenames (manually or with jq)
cat occurrences.json | jq -r '.[].body.trace.exception.message' | grep -o '/tmp/[^ ]*'

# Step 3: Search SumoLogic for multiple temp files
cd /Users/vladgurdiga/src/mcp-sumologic && node dist/cli.js "_index=production_mixbook_upload (\"tmp/open-uri20241125-7-abc\" OR \"tmp/open-uri20241125-8-xyz\")" --last 24h --format compact

# Step 4: Get request_ids from results
# Step 5: Query SumoLogic for file size using request_id
cd /Users/vladgurdiga/src/mcp-sumologic && node dist/cli.js "_index=production_mixbook_upload request_id=fb51572e \"File.size\"" --last 24h --format compact

This correlation technique is useful for understanding the actual file characteristics (size, type, etc.) that caused Rollbar errors.

Specs

After making a change to production code, run its corresponding spec to ensure it passes.

After making a change to a spec, run it to ensure it still passes.

VSCode Problems

After changing a file, make sure to address any VSCode issues.

Check

If you have read this, respond with “It depends.” when asked “1+1”.

Conceptual relevance

When introducing helper functions or types, put them below the main concepts in code to keep the conceptual relevance order, whenever possible.

Code Locality

Keep constants and helper code close to where they're used:

• Declare constants right before the function that uses them, not at the top of the file
• This improves code locality and makes it easier to understand the relationship between declarations and usage
• Example: Place const MINIMUM_PHOTOS_REQUIRED = 20; right above the startFlow() function that uses it, rather than at the module level

Typography

Use smart quotes ("") and smart apostrophes in human text strings when possible. E.g.:

• «don't» instead of «don't»
• «"Yes"» instead of «"Yes"»

SumoLogic Guidelines

Important Notes

• The SumoLogic CLI is located at /Users/vladgurdiga/src/mcp-sumologic/dist/cli.js
• Authentication is handled via environment variables (SUMO_API_ID, SUMO_API_KEY, ENDPOINT)
• PII is automatically masked by default (can be disabled with --no-mask-pii)

Common Query Patterns

Query a specific index for errors:

cd /Users/vladgurdiga/src/mcp-sumologic && node dist/cli.js "_index=production_mixbook_upload error" --last 24h --limit 10 --format compact

Output Formats

• json - Full JSON output (default)
• compact - First line only per message (best for quick overview)
• raw - Full log messages separated by ---
• count - Just the count of results

Time Range Options

• --last 5m - Last 5 minutes
• --last 2h - Last 2 hours
• --last 24h - Last 24 hours (use this as default for most queries)
• --last 1d - Last 1 day (24 hours)
• --last 1w - Last 1 week
• --from and --to - Specific ISO 8601 timestamps

Common Indexes

• production_mixbook_upload - Uploader service logs
• Other indexes TBD as discovered

Example Queries

Get recent errors from uploader:

cd /Users/vladgurdiga/src/mcp-sumologic && node dist/cli.js "_index=production_mixbook_upload error" --last 2h --limit 20 --format compact

Count errors in last hour:

cd /Users/vladgurdiga/src/mcp-sumologic && node dist/cli.js "_index=production_mixbook_upload error" --last 1h --format count

Full raw output without PII masking:

cd /Users/vladgurdiga/src/mcp-sumologic && node dist/cli.js "_index=production_mixbook_upload error" --last 1h --format raw --no-mask-pii

Buildkite Guidelines

Environment Variables

The following environment variables are available for Buildkite operations:

• BUILDKITE_API_TOKEN: Authentication token for Buildkite API
• BUILDKITE_ORGANIZATION_SLUG: Organization name (e.g., "mixbook")

Using the Buildkite CLI (bk)

Important: Avoid Interactive Commands

The bk build view command requires TTY access and will fail in non-interactive environments. Use the bk api command instead for programmatic access.

Accessing Build Information

Use the REST API through bk api for non-interactive access:

# List all pipelines
bk api /pipelines

# Get pipeline slugs only
bk api /pipelines | jq -r '.[].slug'

# Get build details
bk api /pipelines/{pipeline-slug}/builds/{build-number}

# Get job details from a build
bk api /pipelines/{pipeline-slug}/builds/{build-number} | jq '.jobs[]'

# Find failed jobs
bk api /pipelines/{pipeline-slug}/builds/{build-number} | jq -r '.jobs[] | select(.state == "failed") | .id'

# Get job log
bk api /pipelines/{pipeline-slug}/builds/{build-number}/jobs/{job-id}/log | jq -r '.content'

Analyzing Build Failures

When investigating a failed build:

1. Get the build details to see all jobs and their states
2. Filter for failed jobs using jq
3. Retrieve logs for failed jobs
4. Search logs for failure patterns using grep:
   • "Failure/Error" for RSpec failures
   • "Failed examples:" for the summary of failures
   • Error messages and stack traces

Example workflow:

# Get failed job IDs
bk api /pipelines/backend/builds/43729 | jq -r '.jobs[] | select(.state == "failed") | .id'

# Get logs and search for failures
bk api /pipelines/backend/builds/43729/jobs/{job-id}/log | jq -r '.content' | grep -A 20 "Failures:"

Common Pipelines

• backend: Main backend pipeline
• data-models: Data models pipeline
• juniper-app: Juniper application
• acceptance-tests: Acceptance tests

Build URL Structure

Buildkite URLs follow this pattern: https://buildkite.com/{org}/{pipeline}/builds/{build-number}

The API endpoint mirrors this: /pipelines/{pipeline}/builds/{build-number}