NINI
116 lines
2.7 KiB
Markdown
116 lines
2.7 KiB
Markdown
# AGENTS.md Quality Criteria
|
|
|
|
## Scoring Rubric
|
|
|
|
### 1. Commands and Workflows - 20 points
|
|
|
|
20 points: all essential commands documented with context.
|
|
|
|
- Build, test, lint, format, dev, and deploy commands are present when relevant.
|
|
- Development workflow is clear.
|
|
- Common operations and verification expectations are documented.
|
|
|
|
15 points: most commands present, some missing context.
|
|
|
|
10 points: basic commands only, little workflow.
|
|
|
|
5 points: few commands, many missing.
|
|
|
|
0 points: no commands documented.
|
|
|
|
### 2. Architecture Clarity - 20 points
|
|
|
|
20 points: clear codebase map.
|
|
|
|
- Key directories explained.
|
|
- Module relationships documented.
|
|
- Entry points identified.
|
|
- Data flow described where relevant.
|
|
|
|
15 points: good structure overview, minor gaps.
|
|
|
|
10 points: basic directory listing only.
|
|
|
|
5 points: vague or incomplete.
|
|
|
|
0 points: no architecture info.
|
|
|
|
### 3. Non-Obvious Patterns - 15 points
|
|
|
|
15 points: gotchas and quirks captured.
|
|
|
|
- Known issues documented.
|
|
- Workarounds explained.
|
|
- Edge cases noted.
|
|
- Unusual "why this way" rules explained briefly.
|
|
|
|
10 points: some patterns documented.
|
|
|
|
5 points: minimal pattern documentation.
|
|
|
|
0 points: no patterns or gotchas.
|
|
|
|
### 4. Conciseness - 15 points
|
|
|
|
15 points: dense, valuable content.
|
|
|
|
- No filler or obvious info.
|
|
- Each line adds value.
|
|
- No redundancy with code comments or README basics unless Codex specifically needs it.
|
|
|
|
10 points: mostly concise, some padding.
|
|
|
|
5 points: verbose in places.
|
|
|
|
0 points: mostly filler or restates obvious code.
|
|
|
|
### 5. Currency - 15 points
|
|
|
|
15 points: reflects current codebase.
|
|
|
|
- Commands work as documented.
|
|
- File references are accurate.
|
|
- Tech stack and architecture are current.
|
|
|
|
10 points: mostly current, minor staleness.
|
|
|
|
5 points: several outdated references.
|
|
|
|
0 points: severely outdated.
|
|
|
|
### 6. Actionability - 15 points
|
|
|
|
15 points: instructions are executable.
|
|
|
|
- Commands can be copied and run.
|
|
- Steps are concrete.
|
|
- Paths are real.
|
|
- Verification expectations are clear.
|
|
|
|
10 points: mostly actionable.
|
|
|
|
5 points: some vague instructions.
|
|
|
|
0 points: vague or theoretical.
|
|
|
|
## Assessment Process
|
|
|
|
1. Read each instruction file completely.
|
|
2. Cross-reference with the actual codebase.
|
|
3. Check documented commands against package manifests, scripts, and config.
|
|
4. Verify file and directory references.
|
|
5. Score each criterion.
|
|
6. Calculate total and assign grade.
|
|
7. List specific issues.
|
|
8. Propose concrete, concise improvements.
|
|
|
|
## Red Flags
|
|
|
|
- Commands that would fail.
|
|
- References to deleted files or folders.
|
|
- Outdated tech versions.
|
|
- Placeholder template content.
|
|
- Generic advice not specific to the project.
|
|
- Duplicate or contradictory guidance across nested instruction files.
|
|
- An `AGENTS.override.md` that accidentally hides a sibling `AGENTS.md`.
|