77 lines
2.5 KiB
Markdown
77 lines
2.5 KiB
Markdown
|
# Authoring Requirements
|
||
|
|
|
||
|
|
This guide is for teams writing non-functional requirements in this repo. Your requirements will be read by AI agents and validated by deterministic CI checks. Both the requirement AND its test are your responsibility.
|
||
|
|
|
||
|
|
## Requirement Format
|
||
|
|
|
||
|
|
Every requirement must include:
|
||
|
|
|
||
|
|
```markdown
|
||
|
|
## [DOMAIN]-[NNN]: [Title]
|
||
|
|
|
||
|
|
[One-sentence rule statement using MUST / MUST NOT.]
|
||
|
|
|
||
|
|
**Rationale:** Why this policy exists. This is what the AI agent reads to understand intent.
|
||
|
|
|
||
|
|
**Test type:** stack-agnostic | stack-specific
|
||
|
|
|
||
|
|
**Test:** How compliance is verified. Be specific — name the file patterns, config keys, or import paths.
|
||
|
|
```
|
||
|
|
|
||
|
|
## Test Types
|
||
|
|
|
||
|
|
### Stack-Agnostic Tests
|
||
|
|
|
||
|
|
These work regardless of service language. You own them entirely.
|
||
|
|
|
||
|
|
Examples:
|
||
|
|
- File presence/absence: "No `.tf` files in service repos"
|
||
|
|
- YAML structure: "No `kind: Ingress` in Helm templates"
|
||
|
|
- Config patterns: "No pinned infrastructure image tags"
|
||
|
|
|
||
|
|
Implement these directly in `.tests/check.sh` using `find`, `grep`, and standard shell tools.
|
||
|
|
|
||
|
|
### Stack-Specific Tests
|
||
|
|
|
||
|
|
These depend on the service language. You define WHAT to check. Stack teams contribute HOW.
|
||
|
|
|
||
|
|
Your job:
|
||
|
|
1. Write the requirement
|
||
|
|
2. Add a generic check in `check.sh` that reads from adapter files
|
||
|
|
3. Write the adapter pattern for at least one major stack (Java or Python)
|
||
|
|
|
||
|
|
Stack team's job:
|
||
|
|
- Add their language's patterns to `.tests/adapters/<language>.patterns`
|
||
|
|
|
||
|
|
### Adapter File Format
|
||
|
|
|
||
|
|
One pattern per line. Key=value. Keys match the check IDs in `check.sh`.
|
||
|
|
|
||
|
|
```
|
||
|
|
# .tests/adapters/java.patterns
|
||
|
|
cloud_sdk_imports=com\.amazonaws\.|com\.google\.cloud\.|com\.azure\.
|
||
|
|
jwt_libraries=io\.jsonwebtoken|com\.auth0\.jwt
|
||
|
|
auth_endpoints=@PostMapping.*"/login"|@RequestMapping.*"/authenticate"
|
||
|
|
```
|
||
|
|
|
||
|
|
When adding a new stack-specific requirement, add the corresponding key to all existing adapter files (use empty value if not applicable to that stack).
|
||
|
|
|
||
|
|
## Quality Checklist
|
||
|
|
|
||
|
|
Before submitting a requirement:
|
||
|
|
|
||
|
|
- [ ] Rule uses MUST or MUST NOT (not SHOULD)
|
||
|
|
- [ ] Test is deterministic (no LLM, no flaky assertions)
|
||
|
|
- [ ] Test runs in <5 seconds
|
||
|
|
- [ ] Rationale explains WHY, not just WHAT
|
||
|
|
- [ ] At least one adapter pattern exists for a major stack
|
||
|
|
- [ ] Demo violation added to `.demo/` folder
|
||
|
|
- [ ] Requirement doesn't duplicate existing static analysis (Checkstyle, SonarQube, ESLint)
|
||
|
|
|
||
|
|
## What Doesn't Belong Here
|
||
|
|
|
||
|
|
- Coding style rules (use your linter)
|
||
|
|
- Language best practices (use static analysis)
|
||
|
|
- Team-specific conventions (put those in your repo's agent config)
|
||
|
|
- Aspirational guidelines without testable criteria
|