Skip to content

Commit 56e5a47

Browse files
xen0nxen0n
committed
docs: add comprehensive 立意 adoption proposal
Add detailed proposal document explaining: - What 立意 is and the problem it solves - Benefits for the loongfans project specifically - Phased adoption plan (pilot → critical functions → full adoption) - Tooling and workflow documentation - FAQ addressing common concerns Original prompt: > Now for something different -- try to make https://github.com/loongson-community/loongfans adopt the 立意 design pattern. AI-assisted-by: Kimi K2.5 (OpenClaw)
1 parent ad9ef42 commit 56e5a47

1 file changed

Lines changed: 220 additions & 0 deletions

File tree

‎docs/liyi-proposal.md‎

Lines changed: 220 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,220 @@
1+
# 立意 (Lìyì) Adoption Proposal
2+
3+
## Summary
4+
5+
This proposal adopts the [立意 (Lìyì)](https://github.com/liyi-run/liyi) convention for making code intent explicit, persistent, and reviewable in AI-assisted development.
6+
7+
## What is 立意?
8+
9+
立意 is a convention and tooling ecosystem that addresses a core problem in AI-assisted development: the gap between "what the human wanted" and "what the AI produced."
10+
11+
### The Problem
12+
13+
When AI agents (GitHub Copilot, Claude, etc.) write code:
14+
1. Intent is implicit in prompts and context
15+
2. Code can drift from original intent over multiple AI edits
16+
3. Code review becomes difficult when intent isn't documented
17+
4. AI-generated changes are hard to audit for correctness
18+
19+
### The Solution
20+
21+
立意 makes intent **explicit** (written down in sidecar files), **persistent** (version controlled), and **reviewable** (humans approve intent separately from implementation).
22+
23+
## How It Works
24+
25+
### Sidecar Files
26+
27+
For each source file with non-trivial logic, we create a `<filename>.liyi.jsonc` sidecar:
28+
29+
```jsonc
30+
{
31+
"version": "0.1",
32+
"source": "src/node/plugins/loongfans-data/generateDatabase.ts",
33+
"specs": [
34+
{
35+
"item": "generateChipsDB",
36+
"intent": "Transform raw chip YAML data into ChipInfoDB. Validate CPU and chipset entries against schemas...",
37+
"source_span": [145, 210],
38+
"reviewed": false
39+
}
40+
]
41+
}
42+
```
43+
44+
### Source Markers
45+
46+
Use markers in code for requirements and relationships:
47+
48+
```typescript
49+
// @liyi:requirement(data-integrity)
50+
// All data transformations must validate input against schemas...
51+
52+
// @liyi:related data-integrity
53+
function validateChipData(data: unknown): ChipInfo {
54+
// ...
55+
}
56+
```
57+
58+
### The Linter
59+
60+
The `liyi` CLI tool:
61+
- Checks that intent specs match current code (detects drift)
62+
- Validates that `@liyi:requirement` markers have corresponding sidecar entries
63+
- Ensures `@liyi:related` annotations have edges in sidecar specs
64+
- Can auto-correct shifted line numbers
65+
66+
## Benefits for loongfans
67+
68+
### 1. Safer AI-Assisted Refactoring
69+
70+
The device pages are in the middle of a refactor (as noted in AGENTS.md). With 立意:
71+
- Intent for data transformations is documented before changes
72+
- AI agents can verify their changes against documented intent
73+
- Drift is caught at CI time, not in production
74+
75+
### 2. Better Onboarding
76+
77+
New contributors can understand the "why" behind complex functions:
78+
- `generateDevicesDB` intent explains the merge strategy for YAML + markdown
79+
- `validate` intent clarifies schema validation requirements
80+
- No need to reverse-engineer intent from implementation
81+
82+
### 3. Review Efficiency
83+
84+
Code reviews can focus on:
85+
- Does the intent match the requirements? (human judgment)
86+
- Does the implementation match the intent? (liyi checks this)
87+
88+
### 4. Long-term Maintenance
89+
90+
When the original authors are gone:
91+
- Intent specs remain as documentation
92+
- Future AI agents can work within documented constraints
93+
- Requirements traceability (why does this function exist?)
94+
95+
## Adoption Path
96+
97+
### Phase 1: Pilot (This PR)
98+
99+
- Add 立意 documentation to AGENTS.md ✓
100+
- Create example sidecars for critical data transformations ✓
101+
- Add `.liyiignore` for project-specific exclusions ✓
102+
103+
### Phase 2: Critical Functions
104+
105+
Add sidecars for:
106+
- `src/node/routes/chipsPages.ts` — chip page routing logic
107+
- `src/node/routes/devicesPages.ts` — device page routing logic
108+
- `src/client/components/devices/deviceTransform.ts` — device data transforms
109+
110+
### Phase 3: Full Adoption
111+
112+
- Add CI check: `liyi check --fail-on-stale` (optional, non-blocking initially)
113+
- Gradually add sidecars for all non-trivial functions
114+
- Train contributors to write intent specs for new code
115+
116+
## Tooling
117+
118+
### Installation
119+
120+
```bash
121+
# liyi is a Rust tool; install via cargo
122+
cargo install liyi
123+
124+
# Or download prebuilt binary from releases
125+
```
126+
127+
### Development Workflow
128+
129+
```bash
130+
# Check all specs
131+
liyi check
132+
133+
# Fix shifted line numbers (after edits)
134+
liyi check --fix
135+
136+
# Review and approve specs (interactive)
137+
liyi approve src/node/plugins/loongfans-data/*.liyi.jsonc
138+
```
139+
140+
### CI Integration
141+
142+
```yaml
143+
# .github/workflows/ci.yml
144+
- name: Check intent specs
145+
run: |
146+
cargo install liyi
147+
liyi check --fail-on-stale --fail-on-untracked
148+
```
149+
150+
## Comparison with Existing Practices
151+
152+
| Practice | What it checks | What 立意 adds |
153+
|----------|----------------|----------------|
154+
| ESLint | Syntax, style | Intent semantics |
155+
| TypeScript | Type safety | Behavioral contracts |
156+
| Code review | Implementation | Separates intent from implementation |
157+
| Tests | Runtime behavior | Design-time requirements |
158+
159+
立意 is **complementary** to existing practices — it fills the gap between "what the code does" and "what the code should do."
160+
161+
## Example: Data Pipeline Intent
162+
163+
Current state (from this PR):
164+
165+
```typescript
166+
// src/node/plugins/loongfans-data/generateDatabase.ts
167+
168+
// @liyi:requirement(data-integrity)
169+
// All data transformations must validate input against schemas,
170+
// preserve type safety, and ensure foreign key references resolve correctly.
171+
172+
function validate<T>(
173+
data: object,
174+
validator: ValidateFunction,
175+
kind: string,
176+
fileName: string | null = null,
177+
): T {
178+
// implementation
179+
}
180+
```
181+
182+
Sidecar:
183+
184+
```jsonc
185+
{
186+
"item": "validate",
187+
"intent": "Validate parsed YAML data against JSON schema using Ajv. Throw ValidationError with descriptive message including file name and validation errors if schema check fails.",
188+
"source_span": [79, 99],
189+
"reviewed": false
190+
}
191+
```
192+
193+
If someone later modifies `validate` to return `null` instead of throwing, `liyi check` will flag:
194+
- Intent says "Throw ValidationError"
195+
- Implementation returns `null`
196+
- Human review required: is this an intentional change or a mistake?
197+
198+
## Resources
199+
200+
- [立意 repository](https://github.com/liyi-run/liyi)
201+
- [MVP Roadmap](https://github.com/liyi-run/liyi/blob/main/docs/liyi-mvp-roadmap.md)
202+
- [Design Document](https://github.com/liyi-run/liyi/blob/main/docs/liyi-design.md)
203+
204+
## Questions?
205+
206+
- **Q: Does this add overhead?**
207+
A: Only for non-trivial functions. Simple getters/setters are marked `@liyi:trivial` and skipped.
208+
209+
- **Q: What if intent changes?**
210+
A: Update the sidecar intent, run `liyi reanchor` to update hashes, commit both changes.
211+
212+
- **Q: Do we need the Rust toolchain?**
213+
A: Only for CI. Contributors can skip local installation if CI catches issues.
214+
215+
- **Q: Is this ready for production?**
216+
A: 立意 v0.1 is stable and used by its own development. The MVP is feature-complete.
217+
218+
---
219+
220+
**Proposal:** Merge this PR as Phase 1 pilot, then gradually expand coverage based on maintainer feedback.

0 commit comments

Comments
 (0)