> ## Documentation Index
> Fetch the complete documentation index at: https://developers.hubspot.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

---
id: 2de63270-f249-4d63-afe6-6ac033ee5782
---

# Managing projects

> How to keep your HubSpot project healthy as it grows.

AI agents are effective at building features quickly, but can be less reliable at maintaining overall project health over time, since each session starts fresh with no memory of earlier decisions. This page covers the practices that fill that gap.

## Build your agent's instructions over time

<Columns cols={2}>
  <Column>
    You can tell the agent, either in your prompts or in your [agent instructions file](/docs/build-with-ai/foundations#your-agent-instructions-file), to watch for patterns in how you prefer things built or done. Instruct it to ask you to confirm whether a pattern is one you'll want in the future, and then have it save that instruction to your [agent instructions file](/docs/build-with-ai/foundations#your-agent-instructions-file). This means future sessions start with more context about how you work and what you've established, without you having to re-explain it each time.
  </Column>

  <Column>
    <Tree>
      <Tree.Folder name="my-hubspot-project" defaultOpen>
        <Tree.File name="hsproject.json" />

        <Tree.File highlight name="AGENTS.md" />

        <Tree.Folder name="extensions">
          <Tree.Folder name="my-crm-card">
            <Tree.File name="App.jsx" />

            <Tree.File name="package.json" />
          </Tree.Folder>
        </Tree.Folder>
      </Tree.Folder>
    </Tree>
  </Column>
</Columns>

When you scaffold a project, the HubSpot CLI automatically adds [agent context files](/docs/build-with-ai/agent-context-files) directly into your project directories. These are designed to give your agent immediate local context on how HubSpot projects are structured without needing to search the docs right away.

The same principle applies to bugs. When you hit an error during development, have the agent document it in a dedicated `ISSUES.md` file, including the symptom, the root cause, and the fix applied. Then add a standing instruction to your [agent instructions file](/docs/build-with-ai/foundations#your-agent-instructions-file) to check `ISSUES.md` before investigating any new problem. Over time, this prevents the agent from re-solving the same bug in inconsistent ways across different sessions.

<Prompt description="Create an `ISSUES.md` file in the root of this project to track errors we encounter during development. Each entry should include: the symptom or error, the root cause, and the fix applied. Then update my agent instructions file to always check `ISSUES.md` for related prior issues before investigating anything new.">
  Create an `ISSUES.md` file in the root of this project to track errors we encounter during development. Each entry should include: the symptom or error, the root cause, and the fix applied. Then update my agent instructions file to always check `ISSUES.md` for related prior issues before investigating anything new.
</Prompt>

## Validate before uploading

Before pushing any build to HubSpot, run project validation locally to catch JSON schema errors and syntax issues before they reach your account.

If you have the [Developer MCP server](/docs/build-with-ai/developer-mcp-server) installed, ask your agent to run the `validate-project` MCP tool. It validates the project in place and reports errors without triggering a full upload.

If you don't have the Developer MCP server installed, ask your agent to run `hs project validate` via the terminal and report any errors it finds. The `hs project upload` command also catches and reports build errors if something slips through.

Add a validation step to your [agent instructions file](/docs/build-with-ai/foundations#your-agent-instructions-file) so the check happens automatically before each upload rather than only when you remember to ask.

## Use version control

Agents can produce broken code, make unintended changes, or head in the wrong direction. Version control gives you a safety net, a way to step back to a previous state if something goes wrong.

HubSpot's built-in rollback feature requires no setup, and enables you to revert to any previous build, either [in HubSpot](/docs/apps/developer-platform/build-apps/manage-apps-in-hubspot#view-your-app-on-the-project-details-page) or [via the CLI](/docs/developer-tooling/local-development/hubspot-cli/project-commands#deploy-to-hubspot). If a new build has a bug, you can roll back to the previous working build while you fix the issue.

Git is a version control tool that saves snapshots of your code over time. You can use it locally without connecting to any external service like GitHub. Once Git is set up in your project directory, most coding agents, including Claude Code, can handle git operations for you: committing changes, creating branches, and keeping your main codebase safe from broken work.

As your project grows, git also unlocks more advanced workflows: isolated branches keep agent errors away from your main code, and git worktrees for [orchestrating multiple agents](/docs/build-with-ai/best-practices/scaling-up#orchestrating-multiple-agents). If you connect to GitHub, you can also integrate HubSpot Projects via [GitHub Actions](/docs/developer-tooling/third-party-tools/set-up-github-actions) for a deployment workflow driven directly from your repository.

The initial setup (installing git and, optionally, connecting to GitHub) is the part you'll need to handle first. You can do this manually with `git init`, or ask your agent to set up for you:

<Prompt description="I want to use git to version control my HubSpot project. I'm new to Git, so help me get set up from scratch and explain what it does and how it fits into our daily workflow. Once we're set up, update my agent instructions file so future sessions automatically manage git for me, committing related changes regularly and creating branches for new features.">
  I want to use git to version control my HubSpot project. I'm new to Git, so help me get set up from scratch and explain what it does and how it fits into our daily workflow. Once we're set up, update my agent instructions file so future sessions automatically manage git for me, committing related changes regularly and creating branches for new features.
</Prompt>

<Tip>
  If you plan to store your project on GitHub, add a `.gitignore` file to your project to tell git which files to exclude from commits, such as `node_modules/`, local environment files, and build artifacts. Without one, you risk committing files you don't intend to share. If your project doesn't already have one, ask your agent to create a `.gitignore` for a Node.js project.
</Tip>

## Write unit tests

Unit tests are most valuable for the parts of your project that contain actual logic, such as serverless functions, data transformations, utility functions, and API response handling. Testing these gives you an automated check that your code behaves correctly before it reaches HubSpot.

When writing tests, scope each test to a single behavior rather than a single function. Behavior-focused tests are more resilient to refactoring and give you clearer signal when something breaks. Add a standing instruction in your [agent instructions file](/docs/build-with-ai/foundations#your-agent-instructions-file) to run tests before each upload, so the check happens consistently rather than only when you remember to ask.

<Note>
  Project configuration validation is covered by the [validate before uploading](#validate-before-uploading) step. UI extensions can also take advantage of HubSpot's [linting](/docs/apps/developer-platform/add-features/ui-extensions/tools/linting/overview) and [testing](/docs/apps/developer-platform/add-features/ui-extensions/tools/testing/overview) tools, which work for both JavaScript and TypeScript projects.
</Note>

## Review your code as the project grows

This is about periodic, holistic code reviews as your project grows, separate from [reviewing each change before you accept it](/docs/build-with-ai/best-practices/working-with-your-agent#review-before-accepting). Both are useful, at different scales.

Every feature you add expands the surface area of your project. Logic that was clean when you had one app card can turn into duplicated helpers, orphaned functions, and inconsistent patterns by the time you have five. Agents are particularly prone to this. They solve the problem in front of them without always noticing that a similar solution already exists a few files away.

Build periodic code reviews into your process rather than saving them for the end. Good moments to run one include:

* After you finish a feature and before you start the next one.
* Before a significant upload, especially the first one into a production account.
* Any time the project's scope has grown past what you originally planned.

<Prompt description="Now that we've been adding more features to this app and expanding its capabilities, I want you to perform a holistic code review. Check our code for critical issues, bugs, security flaws, dead code, duplicate code, and inefficiencies. Perform this review from the perspective of a seasoned HubSpot developer, searching the developer documentation where you need to confirm how something is meant to work. Before updating any code, report your findings to me, grouped by severity and impact.">
  Now that we've been adding more features to this app and expanding its capabilities, I want you to perform a holistic code review. Check our code for critical issues,  bugs, security flaws, dead code, duplicate code, and inefficiencies. Perform this review from the perspective of a seasoned HubSpot developer, searching the developer documentation where you need to confirm how something is meant to work. Before updating any code, report your findings to me, grouped by severity and impact.
</Prompt>

Two parts of that prompt are doing most of the work:

* **Findings before changes:** asking for a report first keeps you in control of what gets fixed. Some findings will be real problems worth acting on. Others will be preferences you don't share, or deliberate decisions the agent lacks the context to recognize. Work through the list and tell the agent which items to address.
* **A specific reviewer perspective:** asking for the view of a seasoned HubSpot developer produces feedback grounded in platform conventions instead of generic programming advice. This is [anchoring](/docs/build-with-ai/best-practices/working-with-your-agent#anchoring) applied to review rather than to building.

Scope the review to fit the [context window](/docs/build-with-ai/foundations#the-context-window). On anything past a small project, asking the agent to review everything at once fills its context with code and triggers the compaction that costs it the detail it needs to spot subtle problems. Review one extension, one directory, or one feature area at a time. If you keep [specification files](/docs/build-with-ai/foundations#spec-driven-development), have the agent read those first so it understands how the pieces fit together before it starts opening code.

If your agent supports subagents, ask it to deploy one to run the review. The subagent starts with an empty context window, so it evaluates the code as written rather than through the assumptions the main agent formed while building it. An agent reviewing code it just built approaches the review through the lens of its earlier reasoning, which limits how objectively it can evaluate those same decisions.

Fix the high-impact findings first, then run your tests and [validate the project](#validate-before-uploading) before uploading. Once you settle on a review cadence that works, add it to your [agent instructions file](/docs/build-with-ai/foundations#your-agent-instructions-file) so you don't have to remember to ask for it.