# Experiment file

URL: /code/project-structure/experiment-file · Id: `convention:experiment-file`

> An Experiment file holds one Experiment: the Hypothesis, what it varies, the unit, and the Metrics that judge it.

An [Experiment](/business/nouns/experiment) file holds one Experiment: the [Hypothesis](/business/nouns/hypothesis), what it varies, the unit, and the [Metrics](/business/nouns/metric) that judge it.

| Property | Value |
| --- | --- |
| Path | `experiments/[experiment].mdx` |
| Holds | [Experiment](/business/nouns/experiment) |
| Kind | file |
| Leaders | db-first, git-first |
| Team | [Product Team](/agents/product) |
| Written by | [Change.merge](/business/nouns/change/merge) |
| Compiled by | [StartupBuilder](/code/builders/startup) |

### Example
`experiments/longer-trial.mdx` in a Startup repository. Closewise, a sample business, declares a `Close` Noun.

```mdx title="experiments/longer-trial.mdx"
---
hypothesis: A 30-day trial turns more agencies into paying Customers than a 14-day trial, because a trial that spans a month end shows one full Close.
varies: settings.trial
arms: { control: 14d, month: 30d }
unit: visitor
metric: outside-paying-customers
guardrails: [month-3-retention]
window: 45d
minN: 150
---
A 14-day trial ends before most agencies see their first Close.
```

### Props
The frontmatter keys the file takes. The body is its prose.

| Prop | Type | Required | Description |
| --- | --- | --- | --- |
| `hypothesis` | `text` | Yes | The belief under test, stated so the primary Metric can prove it wrong. |
| `varies` | `string` | Yes | What it varies: a file path such as `prompts/support-reply`, or a Setting such as `settings.trial`. |
| `arms` | `json` | No | Each arm’s value, keyed by arm; `control` is the current value. File arms come from `@arm` siblings instead. |
| `unit` | `string` | No | Who is assigned: `visitor`, `customer`, `contact`, `conversation` or `request`. |
| `split` | `json` | No | Each arm’s share of units. Even by default. |
| `metric` | [Metric](/business/nouns/metric) | Yes | The primary Metric that decides the winner. |
| `guardrails` | list of [Metric](/business/nouns/metric) | No | Metrics that stop the Experiment the moment one breaches. |
| `window` | `string` | No | How long it runs before its Readout is read, such as `14d`. |
| `minN` | `integer` | No | The fewest exposed units per arm before a verdict. |

### Generates
[StartupBuilder](/code/builders/startup) compiles it into these records, Verbs and routes.

| Kind | What |
| --- | --- |
| Records | [Experiment](/business/nouns/experiment), [Hypothesis](/business/nouns/hypothesis), [Variant](/business/nouns/variant), [Flag](/business/nouns/flag) |
| Verbs | [Hypothesis.test](/business/nouns/hypothesis/test), [Experiment.start](/business/nouns/experiment/start), [Flag.evaluate](/business/nouns/flag/evaluate) |
| Routes | None. |