skills/vercel__eve
1
0
Fork 0
mirror of https://github.com/vercel/eve.git synced 2026-09-20 05:35:39 +08:00
Code Issues Packages Projects Releases Wiki Activity

chore: updates AGENTS.md (#1714)

Browse Source
This commit is contained in:
Rui
2026-08-06 11:08:23 -04:00
committed by GitHub
parent cb15af65be
commit 19862ccf6f
1 changed files with 25 additions and 13 deletions
Download Patch File Download Diff File Expand all files Collapse all files
AGENTS.md
+25 -13
View File
@@ -70,13 +70,25 @@ line of defense, and every required check must pass before merge.
## Coding principles
1. **Public APIs need docs and tests.** Exported functions, classes, and
important public types get documentation comments and at least one test.
1. **Public APIs are sensitive.** They usually require a research doc proposing the
change, alongside proper e2e tests covering golden paths and known failure modes.
They also require proper and legible documentation.
2. **Small modules over big helpers.** Favor composable primitives with narrow
responsibilities. Split files that carry multiple concerns.
2. **The core is lean and powerful**. The framework core should be simple yet highly
expressible i.e., `eve` can be built with `eve`. This means that changes in
`execution/` and `harness/` should be only done when strictly necessary. The
core should expose hooks and internal APIs so that broad functionality is built
on top of it.
3. **Wrap third-party dependencies.** Do not expose third-party APIs as eve
3. **KISS**. Keep things simple. If there are 5 ways to do something, the simplest
and more obvious one should be the preferred option. Code should be legible and
obvious.
4. **Code is liability**. Each net-new introduced snippet should earn its right
to exist. Common abstractions should be reused. Accidental complexity needs
to be derived to its essence. Entropy must be contained.
5. **Wrap third-party dependencies.** Do not expose third-party APIs as eve
public APIs. Wrap them in eve-owned surfaces so internals can change freely.
Add runtime `dependencies` only as a last resort: prefer vendoring code or
generated artifacts into the repository and listing the source package under
@@ -85,24 +97,24 @@ line of defense, and every required check must pass before merge.
exposure to hijacked nested dependencies that are not pinned directly in the
main lockfile.
4. **Pre-1.0: prefer breaking changes.** Favor correctness and simplicity over
6. **Pre-1.0: prefer breaking changes.** Favor correctness and simplicity over
backwards compatibility. No legacy fallback logic.
5. **Derive names from file paths.** Connection names, tool names, and similar
7. **Derive names from file paths.** Connection names, tool names, and similar
identifiers come from the filesystem path (e.g.
`agent/connections/linear.ts` → `"linear"`). Do not add redundant `name`
fields to definitions.
6. **Name definitions for the protocol they target.** Use
8. **Name definitions for the protocol they target.** Use
`defineMcpClientConnection`, not `defineConnection`.
7. **All runtime functionality lives in the `eve` package.** Never rely on
9. **All runtime functionality lives in the `eve` package.** Never rely on
emitted or generated code for runtime behavior.
8. **Comment why, not what.** Default to no comment; well-named code is the
documentation. Comment only what the code cannot say itself — a non-obvious
why, an invariant, a surprising edge case. Public API docs (principle 1) are
the exception.
10. **Comment why, not what.** Default to no comment; well-named code is the
documentation. Comment only what the code cannot say itself — a non-obvious
why, an invariant, a surprising edge case. Public API docs (principle 1) are
the exception.
Machine-checkable invariants are enforced by `pnpm guard:invariants`, which
runs in the CI lint job. If the guard fails, fix the violation rather than