Skip to content

Commit 8aabbb1

Browse files
8bittitan8bittitan
authored
chore: Add agents and claude files (#202)
1 parent ece879c commit 8aabbb1

2 files changed

Lines changed: 183 additions & 0 deletions

File tree

‎AGENTS.md‎

Lines changed: 182 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,182 @@
1+
# AGENTS.md
2+
Guidance for coding agents working in `github.com/algolia/cli`.
3+
4+
## Scope
5+
- Applies to the whole repository.
6+
- Prefer small, local changes over broad refactors.
7+
- Follow existing Go + Cobra CLI patterns.
8+
9+
## Repository Facts
10+
- Language: Go.
11+
- Module: `github.com/algolia/cli`.
12+
- Go version: `1.23.0`; toolchain: `go1.23.4`.
13+
- Main binary entrypoint: `cmd/algolia/main.go`.
14+
- Docs generator entrypoint: `cmd/docs/main.go`.
15+
- Command tree: `pkg/cmd/...`.
16+
17+
## Cursor / Copilot Rules
18+
- No `.cursor/rules/` directory was found.
19+
- No `.cursorrules` file was found.
20+
- No `.github/copilot-instructions.md` file was found.
21+
- Use this file plus the existing codebase as the repo-specific source of truth.
22+
23+
## Tooling
24+
- Preferred toolchain is listed in `devbox.json`.
25+
- Common tools expected here: `go`, `task`, `golangci-lint`, `gofumpt`, `golines`, `gh`, `curl`.
26+
- E2E tests require `ALGOLIA_APPLICATION_ID` and `ALGOLIA_API_KEY` in the environment or root `.env`.
27+
28+
## Build Commands
29+
Preferred:
30+
31+
```sh
32+
task build
33+
```
34+
35+
```sh
36+
go generate ./...
37+
go build -ldflags "-s -w -X=github.com/algolia/cli/pkg/version.Version=main" -o algolia cmd/algolia/main.go
38+
go build -v ./...
39+
```
40+
41+
- `task build` runs generation first.
42+
- CI also checks `go build -v ./...`.
43+
44+
## Test Commands
45+
All unit tests:
46+
47+
```sh
48+
task test
49+
go test ./...
50+
go test ./... -p 1
51+
```
52+
53+
Single package / single test:
54+
55+
```sh
56+
go test ./pkg/cmd/search
57+
go test ./pkg/cmd/apikeys/list -run Test_runListCmd
58+
go test ./pkg/cmd/apikeys/list -run 'Test_runListCmd/list_tty'
59+
go test ./... -run Test_runListCmd
60+
go test ./pkg/cmd/apikeys/list -run Test_runListCmd -v -count=1
61+
```
62+
63+
E2E tests:
64+
65+
```sh
66+
task e2e
67+
go test ./e2e -tags=e2e
68+
go test ./e2e -tags=e2e -run TestIndices
69+
go test ./e2e -tags=e2e -run TestAgentReady -v
70+
```
71+
72+
- E2E uses `github.com/cli/go-internal/testscript`.
73+
- E2E makes real Algolia API requests.
74+
- Keep E2E runs narrow when possible.
75+
76+
## Lint / Format Commands
77+
78+
```sh
79+
task lint
80+
golangci-lint run
81+
task format
82+
gofumpt -w pkg cmd test internal api e2e
83+
golines -w pkg cmd test internal api e2e
84+
```
85+
86+
- `gosec`
87+
- `gofumpt`
88+
- `stylecheck`
89+
90+
## Generation / Docs Commands
91+
92+
```sh
93+
go generate ./...
94+
go run ./cmd/docs --app_data-path tmp
95+
go run ./cmd/docs --app_data-path tmp --target new
96+
```
97+
98+
Run generation when changing generated flags or API-spec-derived code.
99+
100+
## Fast Local Verification
101+
For substantial changes, prefer this order:
102+
103+
```sh
104+
task format
105+
go test ./path/to/touched/package -run TestName
106+
task lint
107+
task build
108+
```
109+
110+
Use narrower verification for small edits.
111+
112+
## Architecture Guidelines
113+
- Add CLI commands under `pkg/cmd/<domain>`.
114+
- Construct commands with `New...Cmd` functions.
115+
- Keep option structs close to their commands.
116+
- Inject dependencies via `*cmdutil.Factory`.
117+
- Put shared command logic in focused helper packages, usually `pkg/cmdutil`.
118+
- Keep docs-generation logic in `internal/docs` and `cmd/docs`.
119+
120+
## Code Style
121+
### Imports
122+
- Use standard Go grouping: stdlib, third-party, local module.
123+
- Let `gofumpt` handle ordering and spacing.
124+
- Avoid aliases unless they prevent collisions or materially improve clarity.
125+
126+
### Formatting
127+
- Run `gofumpt` on all modified Go files.
128+
- Run `golines` if wrapping becomes awkward.
129+
- Preserve existing multiline layout for structs, literals, and signatures.
130+
131+
### Types And Structs
132+
- Prefer explicit structs for command options and helper state.
133+
- Keep exported APIs minimal.
134+
- Use `any` only where JSON-like dynamic values are genuinely needed.
135+
136+
### Naming
137+
- Exported names: PascalCase.
138+
- Unexported names: camelCase.
139+
- Command constructors: `NewXCmd`.
140+
- Command runners: `runXCmd`.
141+
- Match surrounding test naming, commonly `Test_runXCmd`, `TestNewXCmd`, or `Test_Feature`.
142+
143+
### Cobra Conventions
144+
- Use `RunE`, not `Run`, for command handlers.
145+
- Validate args with `cobra.ExactArgs`, `cobra.MinimumNArgs`, or repo validators.
146+
- Use `ValidArgsFunction` when completion helpers already exist.
147+
- Reuse `cmdutil` helpers for usage text, print flags, JSON flags, and validations.
148+
- Use heredocs for multiline examples and help text.
149+
150+
### Error Handling
151+
- Return errors instead of exiting except in true entrypoints like `main()`.
152+
- Wrap with `%w` when the original cause matters.
153+
- Use plain `return err` when extra context adds no value.
154+
- Prefer actionable CLI-facing error messages.
155+
- Use `cmdutil.FlagErrorf` for invalid flag combinations and user input issues.
156+
- Stop progress indicators on all error paths after starting them.
157+
158+
### I/O And UX
159+
- Use factory-provided `IOStreams` for stdout, stderr, TTY checks, colors, and progress indicators.
160+
- Keep non-TTY output deterministic and script-friendly.
161+
- Use structured output helpers for commands that support `--output`.
162+
- Preserve dry-run behavior: validate, summarize, and avoid side effects.
163+
164+
### Config And Clients
165+
- Read config through `config.IConfig`.
166+
- Acquire API clients from injected functions like `SearchClient` and `CrawlerClient`.
167+
- Do not hardcode credentials, hosts, or profile logic.
168+
169+
### Testing Style
170+
- Prefer table-driven tests for flags, output modes, and edge cases.
171+
- Use `test.NewFactory(...)` and `test.Execute(...)` for command tests.
172+
- Stub API calls with `pkg/httpmock`.
173+
- Use `assert` / `require` from `testify` consistently with nearby tests.
174+
- Use `t.Cleanup(...)` for restoring globals.
175+
- For E2E, add new `txtar` cases under `e2e/testscripts/<area>` and register them in `e2e/e2e_test.go`.
176+
177+
## Change Guidance
178+
- Check for an existing helper before adding a new utility.
179+
- If flag surfaces or generated spec flags change, run `go generate ./...`.
180+
- If command help or command trees change, consider whether docs generation should be rerun.
181+
- Add or update tests when behavior changes.
182+
- Avoid unrelated formatting churn.

‎CLAUDE.md‎

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

0 commit comments

Comments
 (0)