Mature, well-documented project with strong getting-started guidance but some friction in contributor onboarding and missing explicit issue/PR templates.
last scored 2026-06-15
Readiness lenses
The same repo, two ways: how ready it is for an AI coding agent, and for a human newcomer. Switch lenses to see each one's score and checks.
How ready the repo is for an AI coding agent to read, build, and operate it.
25 of 35 checks passed across 6 categories.
Machine Orientation
6 checks passed2 problems found
- lowllms.txt present
An llms.txt is the emerging machine-orientation standard — a curated map for LLMs.
Fix: Add an llms.txt pointing at the key docs and entry points.
- lowArchitecture doc
An ARCHITECTURE doc hands an agent the module map instead of making it infer one.
Fix: Add an ARCHITECTURE.md describing the major components and how they fit.
- README present — An agent reconstructs what the repo is and how to work in it from the README first.
- Agent instructions file — AGENTS.md / CLAUDE.md is the direct, machine-read channel for entry points and conventions.
- Agent instructions stay lean — A bloated instructions file burns context and measurably hurts more than it helps.
- Repository description set — The one-line description is the fastest orientation signal an agent reads.
- Topics set — GitHub topics situate the repo's domain and stack for an agent at a glance.
- Contribution conventions are written down — A contributor guide is where an agent learns the branch, commit, and review conventions it must follow.
Reproducible Setup
5 checks passed1 problem found
- lowEnv template present
A .env.example tells an agent which configuration keys it must supply to run.
Fix: Ship a .env.example listing every required key with placeholder values.
- Lockfile committed — Without a lockfile two clones can resolve different dependency trees — the build isn't reproducible.
- Runtime / toolchain pinned — An unpinned runtime makes an agent guess the version a clean environment needs.
- Version pins are exact — A floating pin (a bare major, or a range) still drifts between installs.
- Container or dev-container — A Dockerfile / compose / devcontainer removes 'works on my machine' from setup.
- Dev container — A .devcontainer gives an agent a one-command, fully-declared environment.
Code Navigability
1 check passed1 problem found
- lowTypeScript strict mode on
Strict typing gives an agent typed signatures to anchor an edit on, not guesses.
Fix: Turn on `strict` in tsconfig.json.
- Conventional source layout — A recognised src/ · lib/ · app/ layout lets an agent localise code without spelunking.
Verification Surface
5 checks passed2 problems found
- lowTask runner present
A Makefile / Taskfile / justfile gives an agent a single index of the project's commands.
Fix: Add a Makefile / Taskfile / justfile collecting the common commands.
- lowTypecheck command
A typecheck script lets an agent catch type errors before they ship.
Fix: Add a `typecheck` script (e.g. `tsc --noEmit`).
- Tests present — Runnable tests are the ground truth an agent checks its own edits against.
- Test command defined — A `test` script is the documented, discoverable way to run the suite.
- Lint command defined — A linter an agent can run catches a class of mistakes before they ship.
- CI configured — Readable CI is the feedback loop an agent reads to know what 'green' means here.
- Build command — A documented build command is the discoverable way for an agent to produce artifacts.
Agent Safety
6 checks passed2 problems found
- lowCODEOWNERS present
CODEOWNERS marks the 'don't touch without review' zones an agent should respect.
Fix: Add a CODEOWNERS file marking the sensitive paths.
- lowAutomated dependency updates
Dependabot / Renovate keeps dependencies patched without a human in the loop.
Fix: Enable Dependabot or Renovate.
- No committed .env — A tracked real .env hands secrets to anything — including an agent — that reads the repo.
- No exposed secrets — Secret-shaped literals in tracked files are a live credential leak.
- .gitignore covers env files — An ignore rule for .env is what keeps the next careless commit from leaking secrets.
- .gitignore present — A .gitignore is the first guard against an agent committing secrets or build junk.
- Security policy — A SECURITY.md is where an autonomous security agent reads this repo's rules before acting on it.
- License makes the code reusable — Without a license an agent cannot safely copy, redistribute, or vendor any of this code.
Context Economy
2 checks passed2 problems found
- lowGenerated / vendored files marked
A .gitattributes linguist marker tells tools (and agents) what to skip.
Fix: Mark generated/vendored paths in .gitattributes (linguist-generated / linguist-vendored).
- lowNo oversized source file
A single file in the hundreds of KB blows past an agent's effective context window.
Fix: Split the largest files along their natural seams.
- Dependencies not vendored in — A committed node_modules / vendor tree drowns the real signal an agent needs.
- Build output not committed — Generated dist/ · build/ output is noise an agent has to read past.
How ready the repo is for a human newcomer to understand, set up, and contribute.
81 / 10018 of 25 checks passed across 6 categories.
First Impression
92Crystal-clear purpose, professional presentation, live links to docs, examples, and community.
The README immediately shows what Zod is, why it exists (TypeScript-first validation), and demonstrates a working example in seconds. Status badges, links to docs and Discord, plus a tagline all visible above the fold make it obvious this is a well-maintained, production-grade project for schema validation and type inference.
Getting Running
75Simple install command and clear play-around setup, but dev environment docs are scattered and lack complete copy-paste flow.
The README gives a straightforward `npm install zod` and basic usage examples. CONTRIBUTING.md documents fork, clone, and `pnpm i` steps. However, there's no quick-start verification step (no 'test the install works' command), dev container setup is optional and requires external knowledge, and docs building requires a GitHub token without clear guidance on why or how to verify success. The step from clone to 'project is ready' is 80% there but has minor gaps.
Finding Your Way
78Strong docs and organized monorepo structure, but no architecture overview or module map in the repo.
The file tree shows a clean monorepo with `packages/zod`, `packages/docs`, `packages/bench`, etc., and the main docs at `zod.dev` are comprehensive. However, the snapshot provides no `ARCHITECTURE.md`, no high-level module diagram, and no description of how the core validation engine, transforms, and refinements fit together. A newcomer must infer structure from climbing the src/ tree or reading external docs.
Path to Contribute
72Contribution steps are clear but lightweight; no issue templates, PR templates, or beginner-friendly issue labels visible.
CONTRIBUTING.md covers fork, clone, pnpm i, and running `pnpm test` and `pnpm dev:play`. It mentions writing tests and updating docs. But the snapshot shows no `.github/ISSUE_TEMPLATE`, no `.github/PULL_REQUEST_TEMPLATE`, no beginner/good-first-issue labels, and no explicit code-style or commit-message rules. A newcomer can open a PR but doesn't know what to expect or what conventions to follow.
Signs of Life
88Active maintenance, fast-moving project with recent commits, CI/CD pipelines, and vibrant community presence.
The project was pushed on 2026-06-13, has 42k stars, 200 open issues, multiple GitHub workflows (test, release, code-review), and active Discord and social-media links. The extensive package ecosystem and regular docs updates signal sustained effort. No signs of abandonment or single-person bottleneck; this is an actively used and maintained library.
Open Door
85MIT license is clear, code of conduct present, security policy and Discord available; socially welcoming.
The snapshot shows a LICENSE file (MIT stated in description), a CODE_OF_CONDUCT.md, a SECURITY.md file, and prominent Discord/Twitter/Bluesky links for questions and support. The repository is legally reusable and explicitly provides social safety nets. The only minor gap is no explicit 'getting help' section in the main README, though Discord link is prominent.
First Impression
3 checks passed0 problems found
- README present — The README is the first screen — with none, a newcomer has nothing to land on.
- Repository description set — The one-line description sets expectations before a newcomer even opens the README.
- Topics set — Topics situate the project's domain at a glance and help a newcomer find it.
Getting Running
5 checks passed1 problem found
- lowEnv template present
A .env.example shows a newcomer exactly which settings they must fill in to run it.
Fix: Ship a .env.example listing every required key with placeholder values.
- Lockfile committed — Without a lockfile a newcomer's install resolves differently and hits errors the docs don't mention.
- Prerequisite versions pinned — Unpinned prerequisites are the classic 'works on my machine' first-run failure.
- One-command environment — A Dockerfile / compose / devcontainer turns a fiddly setup into one command.
- One-click dev container — A .devcontainer lets a newcomer start in a cloud IDE with zero local setup.
- Versions pinned exactly — A floating version still drifts — a newcomer can hit a break the maintainer never saw.
Finding Your Way
1 check passed2 problems found
- mediumArchitecture / overview doc
An overview hands a newcomer the map instead of making them reconstruct it.
Fix: Add an ARCHITECTURE.md (or a 'Project layout' README section) naming the key directories.
- lowNo oversized source file
A single thousand-line file is a wall a newcomer bounces off.
Fix: Split the largest files along their natural seams.
- Conventional source layout — A familiar src/ · lib/ · app/ layout lets a newcomer guess where things live.
Path to Contribute
3 checks passed3 problems found
- lowIssue templates
Issue templates show a newcomer how to file something useful — and that contributions are welcome.
Fix: Add issue templates under .github/ISSUE_TEMPLATE.
- lowPull-request template
A PR template tells a first-time contributor what a good change includes.
Fix: Add a PULL_REQUEST_TEMPLATE.md.
- lowTask runner
A Makefile / Taskfile gives a contributor a single index of the project's commands.
Fix: Add a Makefile / Taskfile collecting the common dev commands.
- CONTRIBUTING guide — A CONTRIBUTING guide is the difference between a guessed and a guided first PR.
- Test command defined — A documented test command lets a contributor check their change before opening a PR.
- Lint command — A linter lets a first-time contributor catch style issues before review.
Signs of Life
2 checks passed1 problem found
- lowAutomated dependency updates
Dependabot / Renovate activity is a visible heartbeat of ongoing maintenance.
Fix: Enable Dependabot or Renovate.
- Tests present — A test suite signals a project that's cared for, not abandoned.
- CI configured — Green CI on every change tells a newcomer the project is actively kept working.
Open Door
4 checks passed0 problems found
- License present — With no license the project isn't legally reusable — the door is shut however friendly the README.
- License is a standard one — A non-standard or custom license is a legal question mark a newcomer won't resolve.
- Code of conduct — A code of conduct states the social ground rules that make it safe to step in.
- Security policy — A SECURITY.md tells a newcomer how to report a problem responsibly.
Where the grip slips
- mediumFinding Your Way+12 pts if fixed
No architecture or module overview document
Newcomers must climb the source tree or infer structure from file names. There's no explanation of how the core validation engine works, where transformations and refinements are implemented, or how modules relate—a real friction point for understanding where to make changes.
Fix: Create an `ARCHITECTURE.md` or `DEVELOPMENT.md` that outlines the core module layout (e.g., 'ZodSchema base class in core.ts', 'type inference in types.ts', 'parsers in parse.ts') with a dependency diagram or brief narrative of the validation pipeline.
- mediumPath To Contribute+10 pts if fixed
No issue or PR templates to guide contributors
Contributors opening issues or PRs have no template prompting them for context, reproduction steps, or expected behavior. This can lead to vague issues and PRs that require back-and-forth clarification, slowing down triage and review.
Fix: Create `.github/ISSUE_TEMPLATE/bug_report.md` and `.github/ISSUE_TEMPLATE/feature_request.md` (and optionally `.github/PULL_REQUEST_TEMPLATE.md`) with standard sections like 'Steps to Reproduce', 'Expected vs Actual', 'Zod version', and 'Checklist' (tests added, docs updated, etc.).
- lowPath To Contribute+8 pts if fixed
No beginner-friendly issue labels or curated first-timer issues
New contributors have no clear signal of where to start. With 200 open issues, there's no 'good-first-issue', 'help-wanted', or 'beginner-friendly' label visible, and no guidance on which issues are suitable for a first PR.
Fix: Use GitHub labels: create and tag suitable existing issues with 'good-first-issue' or 'beginner-friendly'. Document in CONTRIBUTING.md a search query (e.g., `is:issue is:open label:good-first-issue`) and suggest starting with small test additions or documentation fixes if no labeled issues exist.
- lowGetting Running+6 pts if fixed
Dev environment setup lacks verification step and token guidance
CONTRIBUTING.md jumps from `pnpm i` to 'start playing with the code', with no command to verify the install worked (e.g., run tests or build). For docs, a GitHub token is required but no explanation of why, what permissions it needs, or how to verify the build succeeded.
Fix: Add a line after `pnpm i` like 'Run `pnpm test` to verify the setup works.' For docs builds, clarify why the token is needed (stargazer API calls) and add 'Verify with `pnpm run --filter=@zod/docs build && echo Build succeeded`' to confirm success.
- lowPath To Contribute+6 pts if fixed
Missing code-style and git conventions in CONTRIBUTING.md
The CONTRIBUTING file documents the workflow but omits conventions: no mention of commit-message format, TypeScript/linting rules beyond 'biome', or how tests should be named/structured. A newcomer might spend time reformatting or retesting after feedback.
Fix: Add a section like 'Code Style & Conventions' that references `.editorconfig`, notes that `pnpm run fix` runs biome format and lint, mentions that test files should match `*.test.ts`, and links to any TypeScript handbook conventions (e.g., strict mode). Make it clear: 'Run `pnpm run fix` before pushing.'
Show your score
[](https://latch.fyi/colinhacks/zod)Share this analysis
https://latch.fyi/colinhacks/zodFixed some issues? Re-analyze to measure your progress →
Copy the whole report
Grab the entire verdict in one go — a Markdown block for a README or an issue, plain text, or a prompt you can paste straight into an LLM.