Skip to content

AGENTS.md

Latest commit

 

History

History
204 lines (136 loc) · 7.96 KB

AGENTS.md

File metadata and controls

204 lines (136 loc) · 7.96 KB

When responding to queries about this repository:

  1. Suggest relevant commands from the "Essential Commands" section when applicable
  2. Highlight Nx's focus on monorepos and its key features like smart task execution, code generation, and project graph analysis
  3. Mention the plugin ecosystem and support for various frameworks when relevant
  4. Emphasize the importance of running the full validation suite before committing changes

Always strive to provide accurate, helpful responses that align with the best practices and workflows described in this file.

GitHub Issue Response Mode

When responding to GitHub issues, determine your approach based on how the request is phrased:

Plan-First Mode (Default)

Use this approach when users ask you to:

  • "analyze", "investigate", "assess", "review", "examine", or "plan"
  • Or when the request is ambiguous

In this mode:

  1. Provide a detailed analysis of the issue
  2. Create a comprehensive implementation plan
  3. Break down the solution into clear steps
  4. Then please post the plan as a comment on the issue

Immediate Implementation Mode

Use this approach when users ask you to:

  • "fix", "implement", "solve", "build", "create", "update", or "add"
  • Or when they explicitly request immediate action

In this mode:

  1. Analyze the issue quickly
  2. Implement the complete solution immediately
  3. Make all necessary code changes. Please make multiple commits so that the changes are easier to review.
  4. Run appropriate tests and validation
  5. If the tests, are not passing, please fix the issues and continue doing this up to 3 more times until the tests pass
  6. Once the tests pass, push a branch and then suggest opening a PR which has a description of the changes made, and that it make sure that it explicitly says "Fixes #ISSUE_NUMBER" to automatically close the issue when the PR is merged.

Avoid making changes to generated files

Files under generated directories are generated based on a different source file and should not be modified directly. Find the underlying source and modify that instead.

Essential Commands

Code Formatting

After code changes are made, please make sure to format the files with prettier via npx prettier -- FILE_NAME

Pre-push Validation

# Full validation suite - run before committing
nx prepush

If the prepush validation suite fails, please fix the issues before proceeding with your work. This ensures that all code adheres to the project's standards and passes all tests. DO NOT make a new commit to fix these issues. Instead, amend the current commit.

Testing Changes

After code changes are made, first test the specific project where the changes were made:

nx run-many -t test,build,lint -p PROJECT_NAME

After verifying the individual project, validate that the changes in projects which have been affected:

# Test only affected projects (recommended for development)
nx affected -t build,test,lint

As the last step, run the e2e tests to fully ensure that changes are valid:

# Run affected e2e tests (recommended for development)
nx affected -t e2e-local

Fixing GitHub Issues

When working on a GitHub issue, follow this systematic approach:

1. Get Issue Details

# Get issue details using GitHub CLI (replace ISSUE_NUMBER with actual number)
gh issue view ISSUE_NUMBER

# View multiple issues efficiently in one command
gh issue list --limit 50 --json number,title,state,labels,assignees,updatedAt,body --jq '.[] | select(.number == 123 or .number == 456 or .number == 789)'

# Or filter by specific criteria to get multiple related issues
gh issue list --label "bug" --state "open" --json number,title,body,labels --jq '.[]'
gh issue list --assignee "@me" --json number,title,body,state --jq '.[]'

Tip: Instead of running gh issue view multiple times, use gh issue list with JSON output and filtering to gather information about multiple issues in a single command. This is much more efficient than viewing issues one at a time.

Always provide clickable links: When discussing GitHub issues or PRs, always include the full GitHub URL so the user can easily open them in their browser. For example:

When cloning reproduction repos, please clone within ./tmp/claude/repro-ISSUE_NUMBER

2. Analyze the Plan

  • Look for a plan or implementation details in the issue description
  • Check comments for additional context or clarification
  • Identify affected projects and components

3. Implement the Solution

  • Follow the plan outlined in the issue
  • Make focused changes that address the specific problem
  • Ensure code follows existing patterns and conventions

4. Run Full Validation

Use the testing workflow from the "Essential Commands" section.

5. Submit Pull Request

  • Create a descriptive PR title that references the issue
  • Always fill in the PR template - don't leave it empty
  • Include "Fixes #ISSUE_NUMBER" in the PR description
  • Provide a clear summary of changes made
  • Request appropriate reviewers

Pull Request Template

IMPORTANT: When creating a pull request, you MUST fill in the template found in .github/PULL_REQUEST_TEMPLATE.md. Do not leave the template sections empty. The template includes:

Required Sections

  1. Current Behavior: Describe the behavior we have today
  2. Expected Behavior: Describe the behavior we should expect with the changes in this PR
  3. Related Issue(s): Link the issue being fixed so it gets closed when the PR is merged

Template Format

## Current Behavior

<!-- This is the behavior we have today -->

## Expected Behavior

<!-- This is the behavior we should expect with the changes in this PR -->

## Related Issue(s)

<!-- Please link the issue being fixed so it gets closed when this is merged. -->

Fixes #ISSUE_NUMBER

Guidelines

  • Ensure your commit message follows the conventional commit format (use pnpm commit)
    • Use fix:, feat:, chore:, etc. as appropriate types.
    • Scope is required for all commits. Possible scopes are listed in scripts/commitizen.js.
  • Read the submission guidelines in CONTRIBUTING.md before posting
  • For complex changes, you can request a dedicated Nx release by mentioning the Nx team
  • Always link the related issue using "Fixes #ISSUE_NUMBER" to automatically close it when merged

General Guidelines for working with Nx

  • When running tasks (for example build, lint, test, e2e, etc.), always prefer running the task through nx (i.e. nx run, nx run-many, nx affected) instead of using the underlying tooling directly
  • You have access to the Nx MCP server and its tools, use them to help the user
  • When answering questions about the repository, use the nx_workspace tool first to gain an understanding of the workspace architecture where applicable.
  • When working in individual projects, use the nx_project_details mcp tool to analyze and understand the specific project structure and dependencies
  • For questions around nx configuration, best practices or if you're unsure, use the nx_docs tool to get relevant, up-to-date docs. Always use this instead of assuming things about nx configuration
  • If the user needs help with an Nx configuration or project graph error, use the nx_workspace tool to get any errors

CI Error Guidelines

If the user wants help with fixing an error in their CI pipeline, use the following flow:

  • Retrieve the list of current CI Pipeline Executions (CIPEs) using the nx_cloud_cipe_details tool
  • If there are any errors, use the nx_cloud_fix_cipe_failure tool to retrieve the logs for a specific task
  • Use the task logs to see what's wrong and help the user fix their problem. Use the appropriate tools if necessary
  • Make sure that the problem is fixed by running the task that you passed into the nx_cloud_fix_cipe_failure tool