Skip to content

Commit b14ffc6

Browse files
jsundaiDuncanma
jsundai
and
Duncanma
authored
AGENTS.md (#4852)
* draft * agentsmd * add CLAUDE.md pointing to AGENTS.md --------- Co-authored-by: Duncan Mackenzie <duncanma@duncanmackenzie.net>
1 parent 4b8a3bc commit b14ffc6

4 files changed

Lines changed: 178 additions & 2 deletions

File tree

‎.gitignore‎

Lines changed: 0 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -22,8 +22,6 @@ temp/
2222
.env.test.local
2323
.env.production.local
2424
.vs
25-
AGENTS.md
26-
CLAUDE.md
2725
.claude/*
2826
.omc
2927

‎AGENTS.md‎

Lines changed: 151 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,151 @@
1+
# AGENTS.md
2+
3+
Guidance for AI coding agents working in the [Temporal documentation](https://github.com/temporalio/documentation) repository.
4+
5+
## Read these first
6+
7+
| Topic | File |
8+
|-------|------|
9+
| Where content belongs | [INFORMATION-ARCHITECTURE.md](./INFORMATION-ARCHITECTURE.md) |
10+
| React components in MDX | [COMPONENTS.md](./COMPONENTS.md) |
11+
| LLM Markdown pipeline | [MARKDOWN_PIPELINE.md](./MARKDOWN_PIPELINE.md) |
12+
| Component → Markdown mapping | [COMPONENT_REGISTRY.md](./COMPONENT_REGISTRY.md) |
13+
14+
## Repository overview
15+
16+
- **Site:** Docusaurus static site for [docs.temporal.io](https://docs.temporal.io).
17+
- **Content:** MDX files under `docs/`. URLs are served at the site root (`/workflows`), not under `/docs/`.
18+
- **UI code:** React components in `src/components/`. Sidebar navigation is in `sidebars.js`.
19+
- **Redirects:** Legacy URL changes go in `vercel.json` before or alongside file moves.
20+
21+
## Where to put content
22+
23+
Use [INFORMATION-ARCHITECTURE.md](./INFORMATION-ARCHITECTURE.md) to choose the section.
24+
25+
## Style Guide
26+
27+
Follow [STYLE.md](./STYLE.md) and Vale rules in `vale/styles/`. The most common mistakes:
28+
29+
### Temporal terms are proper nouns
30+
31+
Capitalize Temporal core terms. Do not capitalize generic uses.
32+
33+
- Correct: "Register the Activity in the Workflow."
34+
- Incorrect: "Register the activity in the workflow."
35+
36+
Vale enforces many substitutions automatically. See `vale/styles/Temporal/terms.yml`.
37+
38+
### Temporal Service, not Cluster
39+
40+
In body prose, use **Temporal Service**, not **Cluster** or **Temporal Cluster**.
41+
42+
- Correct: "The Worker polls the Temporal Service for tasks."
43+
- Incorrect: "The Worker polls the Cluster for tasks."
44+
45+
Exceptions: **Multi-Cluster Replication**, code/config identifiers, and CLI command names.
46+
47+
### Identifier abbreviation
48+
49+
Outside Temporal core terms, spell out "identifier." For core terms, use `Id` (not `ID` or `id`).
50+
51+
- Correct: "Provide an order identifier as a Workflow Id."
52+
- Incorrect: "Provide an order ID as a Workflow ID."
53+
54+
In code blocks, follow each language's conventions.
55+
56+
### Headings
57+
58+
- Use **sentence case**: "How to get started with Temporal"
59+
- Prefer **infinitive verb forms** or questions: "How to install Temporal", not "Installing Temporal"
60+
- Develop pages: task-oriented headings ("Start a Workflow Execution")
61+
62+
### Writing style
63+
64+
Follow [STYLE.md](./STYLE.md) and the [Google developer documentation style guide](https://developers.google.com/style) for tone (conversational, second person, active voice) and structure (short paragraphs, one idea per sentence). A few additions specific to model output:
65+
66+
- Cut filler that adds no information: "it's worth noting that," "in order to," "simply," "easily," "just."
67+
- Avoid vague intensifiers doing the work a specific fact should do: "powerful," "robust," "seamless," "cutting-edge," "leverage" (use "use"), "unlock," "elevate," "streamline." Replace with what the thing actually does.
68+
- Don't pad a page to look thorough. Prefer brevity over overly-verbose paragraphs.
69+
- Do not add emojis to documentation prose and use em-dashes sparingly.
70+
71+
### Word choice
72+
73+
Prefer common, concrete verbs and nouns.
74+
75+
| Prefer | Instead of |
76+
|--------|------------|
77+
| use | utilize, leverage |
78+
| help | facilitate |
79+
| to | in order to |
80+
| many | numerous, various (when you can be specific, be specific) |
81+
82+
### Tense and time
83+
84+
Document current behavior. Don't make future promises. Tie claims to a version, release note, or release stage when that matters.
85+
86+
| Prefer | Instead of |
87+
|--------|------------|
88+
| Temporal Server v1.31.0 and later supports Cassandra 5.0.4 and later. | A future release will support Cassandra 5. |
89+
90+
## Frontmatter
91+
92+
Typical fields:
93+
94+
```yaml
95+
---
96+
id: page-id
97+
title: Page title
98+
sidebar_label: Short label
99+
description: One sentence for SEO and previews.
100+
keywords:
101+
- keyword
102+
tags:
103+
- Concepts
104+
---
105+
```
106+
107+
- Write `description` as a single clear sentence.
108+
- Do not change `id` or `slug` without a redirect plan.
109+
- Match `tags` and `keywords` to sibling pages in the same section.
110+
- Use existing concepts and keywords. Don't add new ones unless it's a new feature.
111+
112+
## MDX and components
113+
114+
- Pages are `.mdx` with YAML frontmatter (see [Frontmatter](#frontmatter) above).
115+
- Import shared components from `@site/src/components` unless a page uses a one-off import path already established nearby.
116+
- Before adding a component, check [COMPONENTS.md](./COMPONENTS.md) and [COMPONENT_REGISTRY.md](./COMPONENT_REGISTRY.md).
117+
- Reuse existing components (`Tabs`, `SdkTabs`, `CaptionedImage`, `ViewSourceCodeNotice`, etc.) instead of inventing inline HTML patterns.
118+
- Interactive demos live in `src/components/elements/`. Export new public components from `src/components/index.js` when needed.
119+
120+
121+
## URLs and navigation
122+
123+
Adding or moving pages usually requires:
124+
125+
- Updating `sidebars.js` for navigation placement
126+
- Adding redirects in `vercel.json` when the public URL changes
127+
- Fixing internal links across the repo
128+
129+
## Code samples and Snipsync
130+
131+
- Prefer code extracted from CI-enabled sample repos via [Snipsync](https://github.com/temporalio/snipsync).
132+
- Snippets are wrapped in `<!--SNIPSTART id-->` / `<!--SNIPEND-->`. Edit the **source repo** named inside the wrapper, then run `yarn snipsync`.
133+
134+
## Commands
135+
136+
Requires Node.js 24+ and Yarn.
137+
138+
```bash
139+
yarn # Install dependencies
140+
yarn start # Dev server at http://localhost:3000
141+
yarn build # Production build; catches MDX/build errors
142+
yarn check-links # Broken link check (run after build)
143+
yarn snipsync # Refresh Snipsync code snippets
144+
```
145+
146+
Vale linting (style):
147+
148+
```bash
149+
yarn lint:py # Example: lint Python SDK docs
150+
yarn vale # Full Vale run via assembly script
151+
```

‎CLAUDE.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
@AGENTS.md

‎STYLE.md‎

Lines changed: 26 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -21,6 +21,32 @@ Do not capitalize generic versions of Temporal terms. Use generic versions spari
2121

2222
- Incorrect: "Next, register the activity within the workflow."
2323

24+
#### Temporal Service, not Cluster
25+
26+
In body prose, refer to the Temporal backend as **Temporal Service**, not **Cluster** or **Temporal Cluster**.
27+
28+
- Correct: "Connect your Temporal Client to the Temporal Service."
29+
- Incorrect: "Connect your Temporal Client to the Temporal Cluster."
30+
31+
This applies to running instances you operate or connect to ("your Temporal Service", "the Temporal Service", "across the Temporal Service").
32+
33+
Exceptions:
34+
35+
- **Multi-Cluster Replication** and other compound terms that include "Cluster" as part of an official name.
36+
- Code, configuration keys, file paths, CLI commands, and API identifiers (for example, `tctl cluster`, `cluster.pem`).
37+
- Quoting third-party or historical text where the source uses "Cluster".
38+
39+
#### Word choice
40+
41+
Prefer common, concrete verbs and nouns.
42+
43+
| Prefer | Instead of |
44+
|--------|------------|
45+
| use | utilize, leverage |
46+
| help | facilitate |
47+
| to | in order to |
48+
| many | numerous, various (when you can be specific, be specific) |
49+
2450
#### Abbreviation of "identifier"
2551

2652
Do not abbreviate the word "identifier" as "ID", "Id", or "id" unless it's part of a Temporal core term. For core terms, the correct abbreviation is "Id", such as in "Workflow Id" or "Activity Id".

0 commit comments

Comments
 (0)