Team Collaboration SOP and Technical Practices

This page explains how a team, when using Heicode for real project development, can organize AI Code collaboration, prepare project standards, control code consistency, and reduce collaboration risk in large teams through the AIE review mechanism.

Heicode does not require every team to adopt the same development workflow. Teams differ in size, tech stack, project phase, and management style, so a team can continue to keep its own ticketing conventions, code submission conventions, and review habits. What this document provides is a set of recommended practices, focused on solving the problems that large teams commonly run into after introducing AI Code — inconsistent context, fragmented standards, lagging code review, and difficulty aligning at the E2E stage.

Applicable scenarios

When only a few developers are involved in a project, the main benefit AI Code brings is usually improved individual productivity. But once a project enters a stage of multi-person collaboration, multiple modules running in parallel, and multiple repositories delivering together, the question is no longer just "can AI write code," but "are all the AIs and all the developers working from the same shared understanding of the project."

For this reason, this document is more relevant to projects that have already started using AI Code or Agents within a team, especially teams with requirements such as frontend/backend collaboration, collaboration across multiple services, interface integration, permission control, deployment and release, and E2E testing. Small teams can adopt only part of these mechanisms, such as a layered CLAUDE.md, Git-based task tracking, and PR review; large or very large teams are advised to gradually build out a complete set of team standards, a knowledge base, and an AIE review plus dual-review mechanism.

Common problems with AI Code collaboration in large teams

AI Code can significantly increase development speed, but in a large team, if there is no unified standard and no unified review mechanism, the faster development goes, the faster collaboration risk surfaces. Different developers may use different AI Code products, and each AI Code instance may read a slightly different set of project materials, code context, and task background. One module might define its interfaces according to its own understanding, while another module might handle fields, status codes, error formats, or permission logic according to a different standard. By the time these problems are discovered at the E2E stage, a large amount of rework has often already occurred.

Traditional code review relies on human experience, but once AI Code accelerates code output, manual review can easily fall behind. A PR may go through several more iterations before review is even finished; a review comment may not yet have been addressed before a new commit changes the basis of that judgment. Over time, tickets pile up, PR status becomes chaotic, and team members and different AI Agents each form their own understanding — eventually resulting in a situation where "everyone defines their own standard."

The core of these problems is not that AI cannot write code, but that the team has not put the overall project picture, unified standards, code changes, review comments, and ticket status on the same collaboration timeline. Heicode recommends that teams organize their AI development workflow around Git as the main line, and establish consistency control through team standards, a layered CLAUDE.md, tickets, PRs, CI, and AIE review.

A Git-based collaboration timeline

The AI development workflow in team collaboration should be controlled based on Git. Heicode does not replace Git; instead, it adds AI collaboration capability on top of Git's existing workflow. Tickets define the task goal, branches isolate code changes, commits record each change, PRs organize review, CI performs automated checks, review captures feedback, and merge/release move things into delivery.

The recommended main line is as follows:

Issue / Ticket
  ↓
Branch
  ↓
Commit
  ↓
Pull Request
  ↓
CI / Automated checks
  ↓
Review / Review comments
  ↓
Merge
  ↓
Release

Heicode's role in this flow is to help the team read project standards and task context, launch AI Code or an Agent to execute the task, record key decisions made during the task, link code changes to tickets, PRs, and CI, and enter the AIE role during the review stage to perform a consistency review. Teams should try to avoid ad hoc collaboration that bypasses Git, because AI changes without a ticket, a branch, a PR, or a comment trail are very difficult to review, retrospect on, or trace afterward.

Teams Claude.md and the layered standards mechanism

Teams Claude.md is a team-level AI development standards file. It is not a single prompt entry point, nor is it a master document that replaces all project documentation. Its main purpose is to define which files, folders, and project materials Heicode needs to read when a task starts, as well as the team's unified top-level constraints.

In a large project, Teams Claude.md should not carry every detail. It is more like a team-level top-level standard, telling Heicode and AI Code: which materials must be read before starting a task, which standards must not be broken, which directories require caution, and which operations require human approval. More granular rules should be placed alongside the relevant project directory, module directory, or service directory. This avoids letting a single large file balloon out of control, and lets the AI read more accurate, localized context when handling a specific task.

The recommended layering is as follows:

Teams Claude.md
  ↓
Team-level top standard: defines the scope of materials that must be read, unified constraints, prohibited actions, and collaboration boundaries.

Standards files in project directories / module directories
  ↓
Define the specific rules for a given project, module, service, or directory.

A developer's own CLAUDE.md
  ↓
Refines the execution approach based on the current task and personal workflow, but cannot override the constraints in Teams Claude.md.

Issue / Ticket / PR
  ↓
Describes the current task goal, the expected result, the modification boundary, and the acceptance method.

Each developer can write their own CLAUDE.md according to their own tasks and working style, but this file can only refine the execution approach — it cannot override the constraints in Teams Claude.md. For example, a developer can add development commands for the current module, local testing methods, notes on directories they are responsible for, and temporary reminders, but they cannot bypass the team's approval rules, cannot unilaterally change unified interface definitions, and cannot ask the AI to ignore files that Teams Claude.md requires to be read. When Teams Claude.md, project-directory standards, and a developer's CLAUDE.md conflict, Teams Claude.md and the project-level standards take precedence.

Preparing project materials and a knowledge base

A large project cannot rely on handing all documentation to the AI at once. Project materials are usually numerous, and the AI's context may not be able to read them all; documentation also keeps changing, so a static one-time feed easily becomes outdated; and when multiple development streams run in parallel, different AI Code instances may end up reading inconsistent versions of the materials. Because of this, teams need to prepare a materials-access mechanism appropriate to the project's scale.

If a project does not have many materials, they can be placed directly in the Git repository for Heicode to read before a task starts. If a project has a lot of material, it is recommended to prepare a team MCP, a project documentation library, a vector database, interface documentation, database design documentation, permission and security rules, deployment instructions, and real-time records of tickets, PRs, and CI. There can be multiple vector databases, used to store different types of project material, such as product descriptions, interface documentation, technical design, historical issues, FAQs, and deployment manuals.

Under this mechanism, the AI no longer depends on reading all materials at once, but instead retrieves context relevant to the current task through a unified entry point. Heicode can help the AI retrieve relevant information during task execution and review, reducing the information gap between different development streams.

A ticket is not a form to fill out — it defines the AI's output

Heicode does not require users to use a fixed ticket template. Different teams, projects, and scenarios can use different ticket formats. The core of a ticket is not how many fields it has, but making it clear to the AI exactly what it should ultimately return.

An effective ticket should at minimum make the AI understand four things: what you want it to do, what it should ultimately deliver, what it should not do, and how you will judge afterward whether it did the job correctly. The more ambiguous a ticket is, the more freely the AI will improvise; the more clearly a ticket describes the expected result, the easier it is for the team to execute, review, and accept it.

For example, the following ticket is not clear enough:

Help me optimize this module.

A better version is:

Please review the user login module and return:

1. A list of issues with the current login flow;
2. The files you recommend changing;
3. The modified code or a PR;
4. The testing method;
5. Do not modify the registration, permission, or billing modules.

This example is not meant to require every user to write tickets in a fixed template — it illustrates that a ticket should, as much as possible, define the AI's output. For Heicode, a ticket is not there to be filled out as a form, but to make the AI's execution results traceable, reviewable, and acceptable.

AIE: AI-Assisted Integrity Engineer

AIE is a recommended collaboration approach (having Heicode switch to a reviewer's perspective for a second check), not a standalone product feature or system component.

AIE stands for AI-Assisted Integrity Engineer, which can be understood as an AI-assisted consistency engineer. It is not an ordinary developer, nor simply a code review bot. AIE's core responsibility is to help the team check whether the code generated by AI Code stays consistent with the project goals, team standards, ticket requirements, and overall architecture.

In a traditional development workflow, code review is mainly done by humans. But once AI Code substantially increases development speed, the quality and efficiency of manual review are both challenged. A team cannot simply spin up another AI Code instance to do the reviewing, because that may just be introducing another "mind." If this reviewing AI is not grounded in the same unified project materials, team standards, tickets, and PRs, it may form its own understanding, introduce new standards, or even drift from the original goal.

The value of AIE lies in the fact that it is not a freely improvising reviewer, but performs a consistency review grounded in a unified context. It needs to judge whether a code change is reasonable based on Teams Claude.md, project-directory standards, ticket content, PR content, CI results, project materials, and team comments. It cares not only about whether the code runs, but also about whether it exceeds the task boundary, whether it redefines an existing standard, whether it affects other modules, whether tests are missing, whether there are permission or security risks, and whether it is ready to enter the E2E stage.

Dual review: point-of-contact review + AIE review

For important tasks, cross-module tasks, production-related tasks, and large-team collaboration, it is recommended to adopt a dual-review system of "point-of-contact review + AIE review." Point-of-contact review is mainly responsible for the business goal — confirming whether the ticket's goal is correct, whether the user's requirement is satisfied, whether the returned result matches expectations, and whether it can proceed to the next stage. AIE review is mainly responsible for engineering consistency — confirming whether the code complies with team standards, project standards, CI requirements, security requirements, and cross-module collaboration requirements.

Relying on human review alone easily misses technical details and cross-module consistency issues; relying on AIE review alone easily lacks business judgment and requirement judgment. The purpose of the dual-review system is not to add process overhead, but to let the business goal and engineering consistency each be checked separately, instead of putting all the judgment on one role.

When Heicode enters the AIE role, it should automatically read the relevant project files, project materials, ticket information, PR content, and CI results according to team standards, and conduct a review around the code change. AIE's review comments should focus as much as possible on actionable issues — for example, which file does not comply with the standard, which interface may conflict with an existing definition, which test is missing, which change exceeds the scope of the ticket, which CI failure needs to be fixed, and which issue needs confirmation from a human point of contact. AIE should not only output vague comments like "code quality is average," "consider optimizing," or "needs more tests."

The recommended flow is as follows:

Developer submits a PR
  ↓
CI runs automatically
  ↓
Heicode enters the AIE role
  ↓
AIE reads Teams Claude.md, project standards, the ticket, the PR, and CI results
  ↓
AIE outputs review comments
  ↓
Developer responds, fixes, or explains in the PR or ticket
  ↓
Point of contact performs the business review
  ↓
Merge or proceed to E2E once conditions are met

Keeping PRs, comments, and ticket status in sync

Once AI Code participates in development, the team needs to maintain ticket and PR status even more promptly. Because the AI's judgment depends on context, if ticket status, PR comments, and CI results are not updated in time, AIE and other developers may continue to make judgments based on outdated information, leading to duplicate reviews, duplicate changes, or incorrect merges.

Developers should state their current progress in the ticket, respond to review comments in the PR, fix or explain the specific issues AIE raises, and promptly mark resolved issues as resolved. Completed tickets should be closed promptly, and tickets that are no longer being pursued should state the reason and be paused or locked. In a large team, communication delay directly affects the quality of AI collaboration. It is a very common risk in AI collaboration for code to go through several more iterations before a code review is even finished.

Therefore, the team should treat PR comments, ticket status, and CI results as real-time collaboration records, not supplementary material added after the fact. Heicode needs to understand the current task status based on these records, and AIE also needs to judge whether the code still meets the goal based on these records.

Consistency checks before E2E

The E2E stage should not be the first place where inconsistent standards are discovered. If it is not until E2E that inconsistencies in frontend/backend fields, status codes, permission logic, interface contracts, or deployment environments are discovered, the cost of fixing them is usually high. In a large team, the later a consistency problem is discovered, the more tickets, branches, PRs, and people end up involved.

Therefore, before entering E2E, the team should use AIE and human points of contact to check in advance the interfaces, fields, status codes, error formats, permissions, audit, billing, test environment, deployment environment, and unresolved comments across modules. If a problem is found, it should be prioritized for correction in the ticket, PR, and standards files, rather than only being patched temporarily at the testing stage.

AIE's role here is to help the team discover cross-module conflicts and fragmented standards in advance. It does not replace E2E testing — it prevents many problems that should have been resolved at the PR stage from dragging on into the E2E stage.

Technical practice recommendations

Before multiple people start using AI Code at the same time, the team should first prepare Teams Claude.md, project-directory standards, and a basic materials entry point. Without unified standards, the more efficient AI Code becomes, the more likely it is to produce more inconsistent implementations. Important standards should not exist only in chat history or personal experience — they should be written into Git or a traceable documentation library, so that Heicode, AIE, and team members can all read the same material.

Teams also should not write every rule into a single file. Teams Claude.md should remain the team-level top standard, while specific project and module rules should be placed in their corresponding directories. This reduces the risk of a large file spiraling out of control, and lets the AI read more accurate, localized context when handling a specific task.

Complex tasks are not recommended to be handed to the AI all at once. A team can split them by phase into requirement confirmation, technical solution, code implementation, test fixes, staging verification, and production release; or split them by module into user module, permission module, billing module, notification module, and audit module; or split them by risk into low-risk code changes, test environment deployment, staging verification, and production approval. Split tasks are easier for the AI to understand, and easier for AIE and points of contact to review.

A recommended minimal process

For a team just starting to use Heicode, a minimal process can be adopted first. The team first prepares Teams Claude.md, and places the necessary local standards in the project directories. Each task states the expected result through a ticket, and then uses Heicode to launch AI Code or an Agent. Code changes are submitted through a PR; after CI runs automatically, AIE performs a consistency review, followed by a business review from the point of contact, and finally the change is merged or proceeds to E2E.

This process does not require the team to build out a complete system all at once, but it can secure three key points from the start: standards can be read, results can be traced, and reviews can be aligned.

Common anti-patterns

One common anti-pattern is having only a task with no defined result — for example, "help me optimize this system." A ticket like this seems to express a direction, but the AI does not know what it should ultimately deliver, the point of contact does not know how to accept it, and it is even harder for AIE to judge whether the PR has achieved the goal. A better approach is to make the ticket explicitly define a list of issues, a fix plan, a PR, a testing method, and the scope that must not be modified.

Another common anti-pattern is each developer writing their own rules independently. If different CLAUDE.md files conflict with each other, the AI may follow local rules that override the team standard, eventually resulting in inconsistent interfaces, permissions, and deployment at the E2E stage. The correct approach is to use Teams Claude.md to define the team's top-level standard, place project and module rules in their corresponding directories, and let a developer's CLAUDE.md only refine — never override — the team standard.

Another anti-pattern is a PR review that only looks at the code diff. Code that runs does not mean it meets the ticket's goal, nor does it mean it hasn't broken a cross-module convention. A PR review should reference the ticket, Teams Claude.md, project standards, and CI results together. For important tasks, point-of-contact review and AIE review should be used together to reach a judgment.

A final anti-pattern is only unifying standards at the E2E stage. By that point, different modules have often already formed different implementations, the cost of fixing them is high, and the boundaries of responsibility are unclear. Teams should try to use AIE to check consistency in advance at the PR stage, and complete interface, permission, testing, and deployment checks before entering E2E.

Summary

What AI Code improves is development speed, but what a large team truly needs to control is consistency. Heicode recommends that teams build their collaboration timeline around Git, define the team's top-level standard through Teams Claude.md, carry local details through project-directory standards, define the AI's expected output through tickets, record code changes through PRs and CI, and ensure that code, goals, and the overall project stay consistent through the AIE-plus-point-of-contact dual-review mechanism.

The ultimate goal is not to have the team fill out more process steps, but to give the AI development process three capabilities: standards that can be read, a process that can be traced, and results that can be reviewed.