Heicode Project Repository PRD Onboarding Guide

For teams that want to use Heicode Agents in their own code repository.

Downloading the PRD template: go to Enterprise Resources and click GitHub organization binding; above the list of bound repositories, click View or download PRD template and write your document in that format; finally, make sure the file is placed at .heicode/prd.md in each target repository, so the platform can read its milestones and progress automatically.

1. Overall Flow

A project member commits .heicode/prd.md (the requirements document) to the repository
        ↓  The platform reads that file — it's the starting point of the whole flow
The platform generates the technical design (.heicode/sdd.md) and task breakdown (.heicode/task.md)
        ↓  Submit for approval
An enterprise reviewer (AIE) reviews it manually
        ↓  Approved
The team can then have Agents start working on that repository

Until .heicode/prd.md is committed, the subsequent steps do not start. The platform does not infer requirements that aren't written down.

2. Directory Structure

The following directory lives at the root of the project repository:

repository root/
└── .heicode/
    ├── prd.md          requirements document, written by project members
    ├── sdd.md          technical design, generated by the platform or written yourself
    ├── task.md         task breakdown and phasing, generated by the platform or written yourself
    └── config/         governed configuration, pushed by enterprise admins

The path is the only convention — there are no fallback locations

The platform does not try other locations such as PRD.md, docs/prd.md, or README.md. When .heicode/prd.md isn't found, it reports "missing .heicode/prd.md" explicitly.

Using a single path is deliberate: if the platform accepted several locations at once, after a while it would be impossible to tell which copy is the currently valid version.

The same applies to the technical design and task breakdown — only .heicode/sdd.md and .heicode/task.md are read.

3. Prerequisites for the Requirements Document

The following are mandatory; the platform will not write the document if they aren't met:

About credentials

The requirements document enters version control, is read by the generation chain, and is displayed in the approval interface. Any credential appearing in the document is therefore effectively public to everyone who can access the project.

If you need to mention a credential, describe its purpose rather than writing the actual value:

• Recommended: calling the payment gateway requires an API key, bound by ops under enterprise resources
• Not recommended: writing out the key string directly

Document write lock during approval and after sign-off

Once a project enters the Pending review or Approved state, changes to .heicode/prd.md in the repository are no longer written, and the status shows "document write lock in effect".

To change requirements, first return the project to draft state in the console. This mechanism ensures that what was reviewed matches what is actually executed.

4. Writing the Requirements Document

4.1 Only the milestone plan has format requirements

The section structure, ordering, and level of detail in the body of the requirements document are up to the author — the platform neither parses nor comments on them.

The only part with format requirements is the milestone plan, because the platform uses it to produce project progress, milestone comparisons, and cost attribution.

Anchor heading (any of the following is recognized)

# 里程碑
## 里程碑规划
### 3. 实施计划：
## Milestones

Heading levels are relative to the anchor

When the anchor uses ##, milestones use ### and sections use ####. When the anchor uses #, milestones use ## and sections use ###.

The plan can therefore be embedded at any section depth in the document.

Example

## 里程碑规划

### 网关接入
- 目标日期: 2026-09-15
- 开始日期: 2026-09-01

先完成入口打通，本阶段不接入计费。

#### 鉴权改造
- 目标日期: 2026-09-08

#### 灰度放量
- 目标日期: 2026-09-15

### 计费打通
- 目标日期: 2026-09-30

Attribute block rules

• An attribute block is the run of consecutive list items immediately following the heading line, starting with -, *, or +; blank lines between them are allowed
• It ends at the first line that is neither a list item nor blank
• Body text between the attribute block and the next heading is free-form description, which the platform neither parses nor comments on. Adding explanatory text under a milestone is normal

Recognized attribute keys (case-insensitive; Chinese or ASCII colons both work)

Date values must always use YYYY-MM-DD. An attribute in the wrong format is discarded with a notice, but the milestone itself is still recognized — so a single date typo won't cause the whole milestone to be lost.

Points to watch

• When names repeat at the same level, the platform appends #2, #3 automatically and issues a notice. Fixing the duplicate names directly is recommended
• When a section appears before any milestone, it reports orphan_section
• Headings deeper than a section don't take part in parsing, and a notice is issued
• Heading lines inside fenced code blocks (``` or ~~~) are always skipped, so pasting sample Markdown into the document won't create spurious milestones
• A requirements document with no milestone plan is equally valid — the platform issues a single notice and does not treat it as an error, but the project will have no milestone progress

4.2 Milestone identifiers

If you want the console to track rework, wasted consumption, and cost attribution per milestone, you need to tag merge requests with a milestone identifier. Choose either method:

Tag it in the title:

修复登录超时 [milestone:m:第一阶段/s:登录链路]

Or use a branch name starting with milestone/:

milestone/m:第一阶段/s:登录链路

Here m: is the milestone name and s: is the section name, and they must match the names written in .heicode/prd.md. The platform derives node identifiers from names: a milestone is m:<name>, and a section is <parent identifier>/s:<name>.

When untagged, the related metrics show "insufficient data" along with the reason. The platform does not infer which member belongs to which milestone, and does not substitute 0 for an unknown value.

5. What Happens After You Commit

5.1 Scan results

Each time the platform reads the repository it reports an explicit status, and each status maps to one specific action:

5.2 Project statuses

A PRD only needs to state three things clearly: whose problem it solves and what that problem is (background and goals), how exactly it will be solved (features, flows, and interactions), and what counts as success (acceptance criteria and metrics). In form, keep every requirement unambiguous and explicitly prioritized, so that engineering and QA can execute directly from it.