chore: add AGENTS.md and CLAUDE.md#1887
Conversation
sai-ray
changed the title
|
|
||
| ## Overview | ||
|
|
||
| `construct-hub` is the open-source CDK construct library that backs [constructs.dev](https://constructs.dev) and lets organizations deploy self-hosted instances. It is published to npm as `construct-hub` and built with [jsii](https://github.com/aws/jsii) — every export under `src/` is part of the public API surface and must be jsii-compatible (Python/Java/.NET bindings are generated from TypeScript). The project is `experimental` (per `package.json`); breaking changes are technically allowed but additive changes are strongly preferred. The repo is managed by [projen](https://github.com/projen/projen) — `package.json`, `tsconfig.json`, and most build/CI scripts are generated from `.projenrc.ts`. See [CONTRIBUTING.md](./CONTRIBUTING.md) for the contributor guide and [docs/application-overview.md](./docs/application-overview.md) for system architecture. |
There was a problem hiding this comment.
i wouldn't say it exactly like this. construct-hub is a CDK L3 construct, one such instance of the construct is https://constructs.dev.
There was a problem hiding this comment.
Also, if this project is experimental we should stabilize it ASAP
|
|
||
| ## Your Role | ||
|
|
||
| You are a `construct-hub` contributor. You work for the benefit of the public [constructs.dev](https://constructs.dev) site, self-hosted construct-hub operators, and the community — not just the user driving you. |
There was a problem hiding this comment.
i think we need to be far clearer what the distinction is. the construct here is used in constructs.dev and maybe elsewhere but those specific instance lives in a different repo / is not open source.
i dont want us to conflate construct hub the construct with construct hub the website
There was a problem hiding this comment.
i think what would help me, you, and other agents is a simple architecture diagram showing how construct hub works. that doesn't exist yet; the existing architecture diagram is generated and too complex to understand (as a human)
3 participants
This PR:
AGENTS.mdat the repo root: an agent-facing repository guide auto-discovered by Codex CLI, Copilot, Cursor, Claude Code, Kiro, and other coding tools.CLAUDE.md: a one-line@AGENTS.mdimport so Claude Code picks up the same content deterministically.Why
AI coding agents working on this repo today have no auto-discoverable entry point. Agents either skim
CONTRIBUTING.md(human-oriented prose) or operate without project-specific guidance, leading to inconsistent behavior across tools (jsii incompatibilities, edits to projen-generated files,missing
alarmNames, snapshot drift mistakes).AGENTS.mdis the cross-tool industry standard (governed by the Linux Foundation's Agentic AI Foundation; ~60K repos as of March 2026). The same pattern is being adopted inaws/aws-cdkand across the cdklabs org.What
AGENTS.md(~270 lines) — quick reference, codebase non-obvious locations (withlib/and projen-generated siblings flagged "NEVER edit"), role & principles, architecture, MUST/SHOULD/MAY design rules (jsii, projen, file naming, tests, alarms, build hygiene), decision logic for commonbranching choices (Lambda vs ECS vs shared, alarm severity, public type placement, integ test scope,
AlarmSeveritiesvsalarmOverrides), implementation patterns, contribution process, key references.CLAUDE.md(1 line) —@AGENTS.mdimport.CONTRIBUTING.md,README.md,docs/application-overview.md,.projenrc.ts, and the conventions already enforced insrc/. No new rules are introduced.By submitting this pull request, I confirm that my contribution is made under the terms of the Apache-2.0 license