Skip to content

Students Manual

Welcome to grAIder! This manual shows you how to use grAIder to perform local grading and self-reviews of your coursework before submitting it to GitLab.

1. Local Repository Configuration

When your repository is provisioned by your instructor, it will contain a .graider.yml configuration file at its root. This file tells grAIder how your project is structured and where to find the course grading criteria.

A typical .graider.yml looks like this:

course: swe-2026
template: python
criteria:
  repo: course/criteria
  path: grading/rubric.yml

2. Local Grading & Self-Assessment

You can run quality tools, tests, and coverage checks locally to verify that your repository meets all automated grading rules before pushing.

Run this command from the root of your repository:

graider grade

By default, this looks for .graider.yml in the current directory (--repo .).

This command will:

  1. Run the code quality checker (qlty).
  2. Run the language-specific test suite.
  3. Calculate your code coverage.
  4. Generate a local grade-results.json file summarizing the results.

3. Running Local AI Self-Reviews

To check your implementation against the course criteria using AI, you can run a local review.

Note

The AI review needs access to Claude. Either set ANTHROPIC_API_KEY in your shell, or install the claude CLI and run claude login to use a Claude Pro/Max subscription (--backend claude-code).

If you have a local copy of the grading criteria folder (or your instructor has provided access to the criteria repository), run:

graider review --criteria-dir /path/to/criteria

Alternatively, if your .graider.yml specifies a criteria.repo that you have read access to, you can run:

graider review

This will:

  1. Read the criteria from the specified source.
  2. Retrieve only the currently released criteria based on the course milestone cutoff.
  3. Perform an AI evaluation of your codebase using Claude and output a detailed verdict for each criterion.
  4. Save the review report to review-results.json.

Tip

You can preview which criteria are currently in-scope for evaluation without running the actual AI model by using the --dry-run flag:

graider review --dry-run

Revision cadence (self-check → revise → submit)

Feedback only helps if you act on it. The intended loop is:

  1. Self-check — run a formative review while you work; it focuses on what to try next, not a grade:
graider review --formative
  1. Revise — pick up the "Where to next?" steps and improve your code.
  2. Submit — when you are ready, the milestone review runs against your latest commit. A published review shows a Progress since last review section so you (and your instructor) can see which criteria improved.

Your instructor decides whether a milestone review can be re-requested after feedback; where allowed, the grade reflects your post-feedback work.

Reflection and self-assessment

  • Every milestone ships a REFLECTION.md — fill in the three prompts; the review and your viva build on it.
  • Before submitting you can predict your own rubric level per criterion in a self-assessment.yml at the repo root, e.g.: 
    # emerging | developing | proficient | exemplary, keyed by criterion id
"1": developing
"2": proficient
    The report then shows your predicted level next to the review's — the gap is itself useful feedback and trains you to judge your own work. (The grAIder Agent Skill can help you draft it.)

4. Using grAIder with Claude Code

If you use Claude Code for development, you can install the grAIder Agent Skill. This allows Claude Code to directly run graider grade and graider review on your behalf, helping you fix lint errors or failing tests interactively.

Install the Agent Skill

To install the skill globally for Claude Code:

graider skills install

This places the skill files in ~/.claude/skills.

To install the skill locally for the current project only:

graider skills install --project

This places the skill files in ./.claude/skills.

Once installed, you can ask Claude Code questions like:

  • "Run grAIder and help me fix any failing tests."
  • "Am I meeting the current milestone criteria? Run a grAIder review."