Documentation Index
Fetch the complete documentation index at: https://docs.aethis.ai/llms.txt
Use this file to discover all available pages before exploring further.
In this tutorial, you will create a tiny ruleset from source files, review the fields and tests, add guidance, generate rules, publish, and run a decision.
Expected time: 15 minutes. Generation usually takes 1-3 minutes for a small example. More complex policies can take longer.
What you will see
By the end, you will have seen the full authoring loop:
- A real project directory with
sources/, tests/, and guidance/
- Claude Code using Aethis MCP to create and generate a ruleset
- Field discovery before generation, with a human review checkpoint
- Test cases drafted by Claude and reviewed by you
- Guidance hints stored as files and sent to the API
- A generate/test loop until all tests pass
- A published ruleset that returns deterministic decisions
You can paste rules into the conversation, drop files into sources/, or ask Claude Code to fetch source material from the web and save it there. This tutorial uses two small local files so every step is easy to inspect.
If Claude fetches source material from the web, review the saved files before authoring. Web pages can contain summaries, navigation text, or stale content. The rules should compile from the source text you approve.
Before you start
You need:
aethis-cli installed- Aethis MCP installed in Claude Code
- An Aethis API key with authoring access
Install MCP if you have not already:
aethis mcp install --target claude-code
1. Create the project directory
Use the CLI to create a file-based authoring project:
aethis init free-school-meals-child-demo
cd free-school-meals-child-demo
free-school-meals-child-demo/
aethis.yaml
sources/
tests/
scenarios.yaml
guidance/
hints.yaml
.aethis/
sources/ contains the rules or policy texttests/scenarios.yaml contains expected decisionsguidance/hints.yaml contains subject-matter guidance for generation.aethis/ stores local tool state such as project IDs
2. Add two source files
Create sources/age-rule.md:
# Age rule
A child is eligible under this tutorial rule only if the child is aged 4 to 15 inclusive at the start of the relevant school year.
A child aged 3 is too young. A child aged 16 or older is outside this tutorial rule.
sources/school-type-rule.md:
# School type rule
A child is eligible under this tutorial rule only if the child attends a state-funded school.
A child who attends an independent school is not eligible under this tutorial rule.
A child who is home educated is not eligible under this tutorial rule.
This tutorial covers only the child eligibility gate. It does not assess household income, benefits, universal infant entitlement, or sixth-form rules.
3. Add initial guidance
Open guidance/hints.yaml and replace the placeholder with:
hints:
- text: >
This project covers only the child eligibility gate. Do not include
household income, benefits, universal infant entitlement, or sixth-form rules.
process_type: rule_generation
- text: >
child.age is an integer age in whole years at the start of the school year.
The age range is inclusive: age 4 passes and age 15 passes.
process_type: field_extraction
- text: >
child.school_type is an enum with values state_funded, independent,
home_educated. Only state_funded qualifies.
process_type: field_extraction
4. Ask Claude Code to inspect the project
In Claude Code, ask:
Use Aethis MCP to author the rules in this project directory.
Read all files in sources/ and guidance/hints.yaml.
First tell me the fields you expect, then draft tests and stop for my review.
Do not publish anything until I approve the tests and all tests pass.
| Field | Type | Expected values |
|---|
child.age | integer | Whole years at the start of the school year |
child.school_type | enum | state_funded, independent, home_educated |
5. Review the tests
Ask Claude to write the tests into tests/scenarios.yaml. The reviewed file should look like this:
tests:
- name: "Age 4 at state-funded school - eligible"
inputs:
child.age: 4
child.school_type: state_funded
expect:
outcome: eligible
- name: "Age 15 at state-funded school - eligible"
inputs:
child.age: 15
child.school_type: state_funded
expect:
outcome: eligible
- name: "Age 3 at state-funded school - too young"
inputs:
child.age: 3
child.school_type: state_funded
expect:
outcome: not_eligible
- name: "Age 16 at state-funded school - too old"
inputs:
child.age: 16
child.school_type: state_funded
expect:
outcome: not_eligible
- name: "Age 10 at independent school - not eligible"
inputs:
child.age: 10
child.school_type: independent
expect:
outcome: not_eligible
- name: "Age 8 home educated - not eligible"
inputs:
child.age: 8
child.school_type: home_educated
expect:
outcome: not_eligible
Tests are your review surface. Passing tests mean the generated rules match the reviewed test suite. They do not prove your source material is complete.
6. Create the MCP project and discover fields
After you approve the tests, ask Claude:
Create the Aethis project with aethis_create_ruleset using the source files,
the reviewed tests, and the guidance hints. Then run aethis_discover_fields
and stop so I can review the discovered fields before generation.
aethis_create_ruleset({
name: "Free School Meals child demo",
section_id: "free_school_meals_child_demo",
source_text: "<combined reviewed source files>",
test_cases: ["<reviewed tests>"]
})
aethis_add_guidance({ project_id, guidance_text, process_type })
aethis_discover_fields({ project_id })
child.age int
child.school_type enum: state_funded, independent, home_educated
7. Generate and test
When the field discovery looks right, ask:
Generate and test the ruleset. If any test fails, explain the failure before
adding more guidance.
aethis_generate_and_test({ project_id })
age_range: child.age >= 4 AND child.age <= 15
school_type_state: child.school_type == "state_funded"
The age bounds are inclusive. Age 4 and age 15 should both pass.
Regenerate and run the tests again.
8. Publish
Only publish after the test gate is green:
Publish the ruleset with aethis_publish. Tell me the ruleset_id and test count.
aethis_publish({ project_id })
If generation times out in the client, it may still finish server-side. Ask Claude to check the project status or run the tests again before assuming generation failed.
9. Run two decisions
Ask Claude:
Run a decision for a 10-year-old at a state-funded school. Include the trace.
aethis_decide({
ruleset_id: "<published_ruleset_id>",
field_values: {
"child.age": 10,
"child.school_type": "state_funded"
},
include_trace: true
})
{
"decision": "eligible",
"trace": {
"age_check": "satisfied",
"school_type_check": "satisfied"
}
}
Now test a 10-year-old at an independent school. Include the trace.
not_eligible, with school_type_check not satisfied.
10. Export guidance back to files
During a conversation, Claude may add guidance directly through MCP. Export active guidance back into the project so it remains reviewable and version-controlled:
aethis guidance export --project-id <project_id> --output guidance/hints.yaml
aethis guidance import guidance/hints.yaml --project-id <project_id>
guidance/hints.yaml as the human-reviewed record of the SME guidance that shaped generation.
The pattern
For a first authoring session, keep the loop this small:
Put source text in files
Start with one small section. Do not begin with a whole Act, handbook, or policy manual.
Review fields and tests
Let Claude draft them, but approve them yourself. Boundary tests matter more than volume.
Review guidance
Keep guidance specific and scoped. Export MCP-added guidance back to guidance/hints.yaml before review.
Generate, publish, decide
Publish only after the test gate is green, then call aethis_decide against the published ruleset.