[Question] Help me understand why this exists

Aperta
  • Qualcosa non va?
#130 2 commenti 6 reazioni 0 assegnatari Vedi su GitHub

Nessuno ha ancora preso questa issue.

Valutazione

Difficoltà
5/5
Tempo stimato
Più di una settimana
Idoneità per principianti
20/100
Tipo di issue
Documentazione
Chiarezza
Da chiarire
Stato di attività
Ferma
Stack tecnologico
markdown
Ambito
documentation

Direzione di ricerca

Start by reading the README.md guidance and the quoted AGENTS.md rationale in the issue. The issue does not identify a file change, implementation entry point, or acceptance criteria; a maintainer would first need to decide whether the documentation policy should change and define what a completed update means.

Scritto dal modello di indicizzazione a partire dal testo della issue.

Descrizione

README.md files are for humans: quick starts, project descriptions, and contribution guidelines.

Why wouldn't this information be useful to agents?

AGENTS.md complements this by containing the extra, sometimes detailed context coding agents need: build steps, tests, and conventions that might clutter a README or aren’t relevant to human contributors.

Why would clear and concise build steps be more useful to agents than to humans?

Why would clutter not hurt humans?

We intentionally kept it separate to:

Give agents a clear, predictable place for instructions.

As a human, I too want instructions in a clear, predictable place. That's README.md.

Keep READMEs concise and focused on human contributors.

Why is concise information uniquely valuable to human contributors? What's the difference between agents and human contributors when it comes to preferring a high signal, low noise README ?

Provide precise, agent-focused guidance that complements existing README and docs.

What about good guidance is agent-focused?

A good README is concise while complete, and should service humans and agents the same way. Aren't LLMs trained on human writing?

This project reminds me of the times that Search Engine Optimization was thought to mean something other than just having a well structured site with lots of useful content. There's a reason Search Engines have switched to regular browsers for crawling sites: websites need to be written for people. Search engines rank sites based on that.

I strongly believe AGENTS.md discourages writing and maintaining good README.mds.

Lingua principale
TypeScript
Stelle
24.8k
Fork
1.9k
Nessuna PR unita negli ultimi 30g

Preparare l'ambiente

Questo progetto non fornisce container di sviluppo, Dockerfile né guida per i contributori, quindi l'ambiente è a tuo carico: parti dal suo README e consulta la nostra guida al primo contributo per i passaggi generali.

Come iniziare

  1. Leggi tutta la issue e poi la guida ai contributi del progetto.
  2. Commenta sulla issue per dire che te ne occupi tu — evita che due persone facciano lo stesso lavoro.
  3. Fai un fork del repository e lavora su un branch.
  4. Apri una pull request che faccia riferimento al numero della issue.

Altre issue di agentsmd/agents.md

Tutte le issue di agentsmd/agents.md

Issue simili

Altre issue su TypeScript

Ricevi le nuove issue nella tua casella

Un breve riepilogo di issue GitHub adatte ai principianti.