Miguel Prieto
19db40150d
The GitHub Account section hardcoded a specific contributor's account (nthmost-orkes) for all gh CLI commands. This would cause every other contributor's Claude Code to file PRs and issues under the wrong account. Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>
59 lines
2.8 KiB
Markdown
59 lines
2.8 KiB
Markdown
# CLAUDE.md — conductor (server repo)
|
|
|
|
Instructions for Claude Code working in this repository.
|
|
|
|
## Writing Documentation
|
|
|
|
Documentation in this project is **derived from source**, not composed from memory or intuition. The workflow is: open the source → read what's there → write the doc from what you find. The source is the spec; the doc is a rendering of it.
|
|
|
|
Concrete reason this matters: a curl equivalent for `conductor workflow start --sync` was once written as `POST /api/workflow/{name}/run` — an endpoint that does not exist. Opening `WorkflowResource.java` first would have given the correct path (`POST /api/workflow/execute/{name}/{version}`) immediately.
|
|
|
|
### For each content type, start here
|
|
|
|
**REST endpoint or curl example**
|
|
1. Open the controller: `rest/src/main/java/com/netflix/conductor/rest/controllers/`
|
|
2. Find the method by its `@PostMapping`/`@GetMapping` annotation — copy the path literally.
|
|
3. Read the method signature for query params, path variables, and request body.
|
|
4. Write the curl from what you just read.
|
|
|
|
**CLI command or flag**
|
|
1. Open `conductor-cli/cmd/*.go` (separate repo under this workspace).
|
|
2. Find the `cobra.Command` for the subcommand and read its `Flags()` declarations.
|
|
3. Write the example from what you just read — flag names, types, and defaults.
|
|
|
|
**SDK code example (Python, JS, Java, Go)**
|
|
1. Open the SDK source file for the method you're documenting.
|
|
2. Read the method signature and required parameters.
|
|
3. If a working test exists for that method, use it as the starting point.
|
|
4. Write from the signature — do not infer from the method name alone.
|
|
|
|
**Expected output block**
|
|
1. Get real output: run the command, or find it in test fixtures or CI logs.
|
|
2. Paste verbatim. Do not construct output that "looks right."
|
|
3. For variable fields (IDs, timestamps), use annotated placeholders like `<workflow-id>`.
|
|
|
|
**Editing an existing section**
|
|
- Before changing anything, read every code block and command in the section.
|
|
- Verify each one using the steps above, not just the block you plan to change.
|
|
- Fix anything you find while you're there.
|
|
|
|
### When you can't verify
|
|
|
|
If a running server or CLI is unavailable:
|
|
- Add `<!-- TODO: verify against live server -->` in the file.
|
|
- Note it explicitly in the PR description.
|
|
- Do not write an unverified example and leave it unmarked.
|
|
|
|
### Key source locations
|
|
|
|
| Content | Where to look |
|
|
|---|---|
|
|
| REST API routes | `rest/src/main/java/com/netflix/conductor/rest/controllers/` |
|
|
| Workflow sync execution | `WorkflowResource.java` → `executeWorkflow()` at `@PostMapping("execute/{name}/{version}")` |
|
|
| Task routes | `TaskResource.java` |
|
|
| CLI subcommands and flags | `conductor-cli/cmd/workflow.go`, `cmd/task.go`, etc. |
|
|
|
|
## Other Guidelines
|
|
|
|
See [AGENTS.md](AGENTS.md) for full project conventions: code style, testing, dependency pinning, PR guidelines.
|