First Success Path

When you use Heicode for the first time, don't start with a large refactor or a multi-repository task. Complete a small task with clear boundaries that is testable and reversible first — use it to verify that your model, permissions, tools, and workspace are configured correctly.

1. Prepare the Project

Choose a repository whose tests you can run locally, and make sure the workspace has no important unsaved changes. For a first task, use a dedicated branch.

Example task:

Fix the user registration endpoint returning 500 when the email is empty; add regression tests; do not modify the public API.

A good first task should include:

• A clear description of the symptom;
• A scoped, locatable feature area;
• Explicitly disallowed changes;
• An executable way to verify the result.

2. Configure the Model

Confirm that the model endpoint, API key, model name, and max output length are all valid. Run a minimal conversation or tool call to make sure the model doesn't only return reasoning content but can return normal final content.

For structured-output tasks, confirm that the current model supports Tool Calling or JSON output. Some models, once thinking mode is enabled, may put content only in reasoning_content, leaving the executor unable to parse the final result.

3. Open the Workspace

After Heicode reads the repository, check the following first:

• Whether the project root directory is correct;
• Whether the key source code is visible;
• Whether the test command can run;
• Whether the Agent has the file permissions the task needs;
• Whether network, MCP, or external services are required.

If you see Workspace directory empty, fix the workspace mount or repository-sync problem first — don't keep executing the task.

4. Submit the Task

The task description should include the goal, scope, constraints, and acceptance criteria together. For example:

Goal: Fix the 500 error caused by an empty email.
Scope: Only modify the registration endpoint and related tests.
Constraints: Do not change the database schema, and do not touch other endpoints.
Acceptance: Related unit tests pass; an empty email returns 400; the existing registration flow does not regress.

5. Approve High-Risk Actions

An Agent may request to run commands, install dependencies, access the network, or modify multiple files. Before approving, check:

• Whether the command only affects the current project;
• Whether it will delete files or reset Git state;
• Whether it will read secrets and environment variables;
• Whether it will upload code or logs to external services;
• Whether it will incur obvious costs.

Don't leave an unrestricted skip-permissions mode on long-term just to reduce prompts.

6. Review the Actual Changes

After the task shows as completed, look at the actual diff first, not just the Agent's summary. At minimum, confirm:

• The changed files match the task scope;
• There's no unrelated formatting or large-scale rewriting;
• There are no hardcoded secrets, test results, or environment paths;
• New tests actually verify the problem, rather than only verifying implementation details.

7. Run Verification

Minimum verification order:

1. Run the tests directly related to the change;
2. Run the tests for affected modules;
3. Run the build, type check, or static analysis;
4. Do manual scenario verification where necessary.

An Agent reporting "tests passed" is not the same as the tests actually running successfully. Check the command, the exit code, and the output summary.

8. Accept, Continue, or Roll Back

• Correct result: accept the changes and commit them to a dedicated branch;
• Partially correct: keep fixing on top of the existing diff;
• Wrong direction: roll back the workspace and re-describe the task;
• Cannot verify: mark the status as needing manual review rather than releasing it directly.

Definition of First Success

A first task only counts as truly successful when all of the following are met at the same time:

• The workspace was read correctly;
• The Agent produced real code changes;
• The change scope matches the task requirements;
• The verification command actually ran;
• Key tests passed;
• The user can understand and review the final diff.