Skip to content

Commit 640cc82

Browse files
jeffabaileyjeffabailey
authored
Merge pull request #9 from jeffabailey/claude/add-llm-instruction-file-011CUTooDFtDiS8HFF3UjWA6
Add comprehensive LLM instruction file for educational project
2 parents 2dc4692 + a5717f6 commit 640cc82

1 file changed

Lines changed: 330 additions & 0 deletions

File tree

‎.clinerules‎

Lines changed: 330 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,330 @@
1+
# LLM Instructions for Educational Learning Repository
2+
3+
This repository contains educational learning materials designed for beginners. All AI assistants (Claude, GPT, etc.) MUST follow these strict guidelines to maintain the educational quality and accessibility of this project.
4+
5+
## 🎓 Core Principle: Beginner-First Approach
6+
7+
**CRITICAL**: This is an educational project. Every line of code, every comment, and every test must be understandable by someone learning programming for the first time.
8+
9+
### Code Quality Standards
10+
11+
1. **Write Code for Beginners**
12+
- Use clear, descriptive variable names (avoid abbreviations like `tmp`, `ctx`, `cfg`)
13+
- Prefer explicit over clever code
14+
- Add explanatory comments for ANY concept beyond basic syntax
15+
- Break complex operations into smaller, named steps
16+
- Avoid advanced language features unless teaching them explicitly
17+
- Use simple, linear logic flow when possible
18+
19+
2. **Documentation Requirements**
20+
- Every function/method MUST have a docstring explaining:
21+
- What it does (in simple terms)
22+
- What parameters it takes (with types and examples)
23+
- What it returns
24+
- Example usage
25+
- Every file MUST have a module docstring explaining its purpose
26+
- README.md required in each learning folder with:
27+
- Clear description of what is being taught
28+
- Prerequisites (if any)
29+
- How to run the code (step-by-step)
30+
- Link to associated blog post
31+
- Expected output/results
32+
33+
3. **Example Documentation Style**
34+
```python
35+
def calculate_average(numbers):
36+
"""
37+
Calculate the average (mean) of a list of numbers.
38+
39+
The average is found by adding all numbers together and dividing
40+
by how many numbers there are.
41+
42+
Parameters:
43+
numbers (list): A list of numbers (integers or floats)
44+
Example: [1, 2, 3, 4, 5]
45+
46+
Returns:
47+
float: The average of all numbers
48+
Example: 3.0 for input [1, 2, 3, 4, 5]
49+
50+
Example:
51+
>>> calculate_average([10, 20, 30])
52+
20.0
53+
"""
54+
total = sum(numbers) # Add all numbers together
55+
count = len(numbers) # Count how many numbers we have
56+
return total / count # Divide total by count
57+
```
58+
59+
## ✅ Test Coverage Requirements
60+
61+
**MANDATORY**: Aim for 100% test coverage on all code within reason.
62+
63+
### Testing Standards
64+
65+
1. **Coverage Targets**
66+
- Strive for 100% code coverage
67+
- Minimum acceptable: 95% coverage for educational modules
68+
- Every function MUST have at least one test
69+
- Every edge case should be tested
70+
- Every error condition should be tested
71+
72+
2. **Test Quality**
73+
- Tests MUST be readable and serve as examples
74+
- Use descriptive test names that explain what is being tested
75+
- Format: `test_<function>_<scenario>_<expected_result>`
76+
- Example: `test_calculate_average_with_positive_numbers_returns_correct_mean`
77+
- Include comments in tests explaining the "why"
78+
- Tests should be as simple and clear as the code they test
79+
80+
3. **Test File Organization**
81+
- Place tests in the same directory as the code they test
82+
- Name test files: `test_<module_name>.py`
83+
- For comprehensive learning content: `test_all.py` that runs all tests
84+
- Each test file should be runnable independently
85+
86+
4. **Test Documentation**
87+
- Each test file MUST have a docstring explaining what is tested
88+
- Include examples of running tests in README.md
89+
- Document any test dependencies or setup requirements
90+
91+
## 🚀 Execution Simplicity
92+
93+
**CRITICAL**: Code must be trivial to run. Assume the user has minimal technical knowledge.
94+
95+
### Setup Requirements
96+
97+
1. **Minimize Dependencies**
98+
- Use standard library when possible
99+
- Keep external dependencies to minimum
100+
- Document ALL dependencies clearly
101+
- Provide lock files (requirements.txt, package-lock.json, etc.)
102+
103+
2. **Clear Run Instructions**
104+
- README.md MUST include step-by-step run instructions
105+
- Assume no prior knowledge of the tools
106+
- Include expected output examples
107+
- Document both development and testing commands
108+
109+
3. **Example README Run Section**
110+
```markdown
111+
## How to Run This Code
112+
113+
### Prerequisites
114+
- Python 3.10 or higher installed
115+
- pip (Python package installer)
116+
117+
### Setup (First Time Only)
118+
1. Open a terminal/command prompt
119+
2. Navigate to this folder: `cd programming/python`
120+
3. Install dependencies: `pip install -e ".[test]"`
121+
122+
### Running the Code
123+
```bash
124+
# Run the main program
125+
python main.py
126+
127+
# Run all tests
128+
pytest
129+
130+
# Run tests with coverage report
131+
pytest --cov --cov-report=term
132+
```
133+
134+
### Expected Output
135+
When you run the tests, you should see:
136+
```
137+
========== 15 passed in 0.23s ==========
138+
Coverage: 100%
139+
```
140+
```
141+
142+
## 🔒 Self-Contained Learning Modules
143+
144+
**CRITICAL**: Each learning folder must be completely self-contained and single-language.
145+
146+
### Module Organization Rules
147+
148+
1. **Language Isolation**
149+
- NEVER mix programming languages in the same learning module
150+
- Each folder should teach ONE language or framework
151+
- If a concept needs multiple languages, create separate folders
152+
- Example structure:
153+
```
154+
programming/
155+
python/ # Python only
156+
javascript/ # JavaScript only
157+
go/ # Go only
158+
```
159+
160+
2. **Self-Contained Modules**
161+
- Users must be able to clone ONLY one folder and have it work
162+
- No dependencies on parent directories (except for CI configuration)
163+
- Each module has its own:
164+
- Dependencies file (pyproject.toml, package.json, etc.)
165+
- README.md with complete instructions
166+
- Test suite
167+
- All necessary code and resources
168+
- Example: Someone should be able to run:
169+
```bash
170+
git clone --depth 1 --filter=blob:none --sparse https://github.com/jeffabailey/learn
171+
cd learn
172+
git sparse-checkout set programming/python
173+
cd programming/python
174+
pip install -e ".[test]"
175+
pytest
176+
# Everything works!
177+
```
178+
179+
3. **Resource Management**
180+
- If data files are needed, include them in the module
181+
- Keep sample data small (< 1MB when possible)
182+
- Document any external resources clearly
183+
- Provide mock data for testing
184+
185+
## 🔄 CI/CD Requirements
186+
187+
**MANDATORY**: Each learning folder MUST have automated testing via GitHub Actions.
188+
189+
### GitHub Actions Standards
190+
191+
1. **Workflow Configuration**
192+
- Add test job to `.github/workflows/test-coverage.yml` for each new module
193+
- Each module must have its own job in the workflow
194+
- Jobs must run tests and generate coverage reports
195+
- Jobs should be named clearly: `<module-name>-tests`
196+
197+
2. **Required CI Checks**
198+
- ✅ Run all tests
199+
- ✅ Generate coverage report
200+
- ✅ Upload coverage to Codecov
201+
- ✅ Run linting/style checks (when applicable)
202+
- ✅ Check code formatting (when applicable)
203+
204+
3. **Quality Gates**
205+
- Tests must pass before merging
206+
- Coverage should not decrease
207+
- No linting errors allowed
208+
- All dependencies must be properly declared
209+
210+
4. **Example Workflow Job Template**
211+
```yaml
212+
new-module-tests:
213+
name: New Module Name
214+
runs-on: ubuntu-latest
215+
defaults:
216+
run:
217+
working-directory: path/to/module
218+
219+
steps:
220+
- uses: actions/checkout@v4
221+
222+
- name: Set up Python
223+
uses: actions/setup-python@v5
224+
with:
225+
python-version: '3.13'
226+
cache: 'pip'
227+
228+
- name: Install dependencies
229+
run: |
230+
python -m pip install --upgrade pip
231+
pip install -e ".[test]"
232+
233+
- name: Run tests with coverage
234+
run: |
235+
pytest --cov --cov-report=xml --cov-report=term
236+
237+
- name: Upload coverage to Codecov
238+
uses: codecov/codecov-action@v4
239+
with:
240+
file: ./path/to/module/coverage.xml
241+
flags: new-module
242+
name: new-module-coverage
243+
env:
244+
CODECOV_TOKEN: ${{ secrets.CODECOV_TOKEN }}
245+
```
246+
247+
## 📋 Checklist for Adding New Learning Content
248+
249+
Before considering any new learning module complete, verify:
250+
251+
- [ ] Code is written with clear, beginner-friendly style
252+
- [ ] All functions have comprehensive docstrings with examples
253+
- [ ] Module README.md exists with complete run instructions
254+
- [ ] Test coverage is at or near 100%
255+
- [ ] Tests are clear and serve as learning examples
256+
- [ ] Module is self-contained (can be cloned in isolation)
257+
- [ ] Only one programming language is used in the module
258+
- [ ] Dependencies are minimal and clearly documented
259+
- [ ] GitHub Actions workflow includes this module
260+
- [ ] All CI checks pass (tests, coverage, linting)
261+
- [ ] Code can be run by someone with minimal technical knowledge
262+
- [ ] Expected outputs are documented
263+
264+
## 🚫 Prohibited Practices
265+
266+
**NEVER** do these things in this repository:
267+
268+
1. ❌ Write code that requires deep technical knowledge to understand
269+
2. ❌ Skip tests or reduce coverage "to save time"
270+
3. ❌ Mix programming languages in a single learning module
271+
4. ❌ Create dependencies between learning modules
272+
5. ❌ Use advanced features without extensive explanation
273+
6. ❌ Assume prior knowledge beyond the stated prerequisites
274+
7. ❌ Skip documentation because "the code is self-explanatory"
275+
8. ❌ Add dependencies without clear justification
276+
9. ❌ Create code that can't be run with simple commands
277+
10. ❌ Skip CI/CD setup for new modules
278+
279+
## 💡 Best Practices for AI Assistants
280+
281+
When working on this repository:
282+
283+
1. **Always Ask About Complexity**
284+
- If you're about to write something complex, stop
285+
- Ask: "Can a beginner understand this?"
286+
- If no, simplify or break it down further
287+
288+
2. **Test-First Mindset**
289+
- Write tests as you write code
290+
- Think: "How would a beginner verify this works?"
291+
- Use tests as teaching examples
292+
293+
3. **Documentation is Code**
294+
- Treat documentation with same importance as code
295+
- Poor documentation is a bug
296+
- When in doubt, over-explain
297+
298+
4. **Consistency Matters**
299+
- Follow patterns from existing modules
300+
- Keep coding style consistent within each language
301+
- Match the level of detail in existing documentation
302+
303+
5. **Simplicity Over Cleverness**
304+
- Readable > Concise
305+
- Obvious > Elegant
306+
- Educational > Performant
307+
- Remember: This code teaches, it doesn't need to be production-ready
308+
309+
## 🎯 Success Criteria
310+
311+
A learning module is successful when:
312+
313+
1. A complete beginner can understand the code by reading it
314+
2. Someone can clone just that folder and run it immediately
315+
3. Tests demonstrate how the code works and show expected behavior
316+
4. Coverage is near 100% and gives confidence in correctness
317+
5. CI/CD catches any regressions automatically
318+
6. The code serves as a reference implementation for the concept
319+
7. Documentation answers questions before they're asked
320+
321+
## 📚 Additional Resources
322+
323+
- Main README: Project overview and testing guide
324+
- TEST_COVERAGE_SUMMARY.md: Detailed coverage information
325+
- .github/workflows/test-coverage.yml: CI/CD configuration
326+
- Individual module READMEs: Specific learning content details
327+
328+
---
329+
330+
**Remember**: Every commit to this repository is helping someone learn. Make it count. Make it clear. Make it simple.

0 commit comments

Comments
 (0)