Skip to content

Commit ace3741

Browse files
ofriwclaude
ofriw
and
claude
committed
Add Claude Code context files for project guidance
🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
1 parent 9fd0be0 commit ace3741

File tree

2 files changed

+325
-0
lines changed

2 files changed

+325
-0
lines changed

‎CLAUDE.md‎

Lines changed: 93 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,93 @@
1+
# AI Coding Course - Project Context
2+
3+
## Project Overview
4+
5+
This is an **AI Coding Course designed for Senior Software Engineers**. The course teaches experienced developers how to effectively leverage AI coding assistants in production environments.
6+
7+
**Target Audience:** Senior engineers with 3+ years of professional experience
8+
**Estimated Course Duration:** 24-33 hours of hands-on training
9+
10+
## Course Structure
11+
12+
5 progressive modules, each building on the previous:
13+
14+
1. **Fundamentals** (2-3 hours) - Understanding AI coding assistants
15+
2. **Prompting Techniques** (4-5 hours) - Effective communication patterns
16+
3. **Tools & Workflows** (5-6 hours) - Integration and collaboration
17+
4. **Architecture & Design** (6-7 hours) - System design with AI
18+
5. **Advanced Topics** (6-8 hours) - Security, performance, production
19+
20+
## Technology Stack
21+
22+
**Platform:** Docusaurus 3.9.2 (Static site generator)
23+
**Languages:** TypeScript 5.6.2, React 19.0
24+
**Key Features:**
25+
26+
- Live code blocks with `@docusaurus/theme-live-codeblock`
27+
- MDX support for interactive components
28+
- Full-text search with `@easyops-cn/docusaurus-search-local`
29+
- Versioning system for content snapshots
30+
31+
## Development Commands
32+
33+
```bash
34+
# Development
35+
cd website && npm start # Start dev server (localhost:3000)
36+
npm run build # Production build
37+
npm run serve # Preview production build locally
38+
39+
# Deployment
40+
npm run deploy # Deploy to GitHub Pages
41+
```
42+
43+
## Directory Structure
44+
45+
```
46+
/
47+
├── website/ # Docusaurus application
48+
│ ├── docs/ # Course content (MDX files)
49+
│ ├── blog/ # Blog posts and case studies
50+
│ ├── src/ # Custom React components
51+
│ └── static/ # Static assets (images, etc)
52+
├── CLAUDE.md # This file - project context
53+
└── README.md # Project documentation
54+
```
55+
56+
## Tone & Communication Style
57+
58+
**Coworker-level communication** - Professional, direct, no hand-holding
59+
60+
- Assume strong fundamentals (data structures, design patterns, system design)
61+
- Skip basic explanations - link to external docs if needed
62+
- Focus on practical application and production considerations
63+
- Use industry-standard terminology without over-explaining
64+
65+
## Content Philosophy
66+
67+
**Production-Ready Architecture Focus**
68+
69+
- Real-world examples over toy demos
70+
- Scalability and maintainability considerations
71+
- Security and performance implications
72+
- Trade-offs and decision-making criteria
73+
74+
**Minimalism & Clarity**
75+
76+
- Concise explanations
77+
- Code examples that compile and run
78+
- Clear learning objectives per lesson
79+
- Hands-on exercises with real scenarios
80+
81+
## Key Configuration Files
82+
83+
- `website/docusaurus.config.ts` - Site configuration
84+
- `website/sidebars.ts` - Auto-generated from docs structure
85+
- `website/package.json` - Dependencies and scripts
86+
- `.github/workflows/deploy.yml` - GitHub Pages deployment
87+
88+
## Deployment
89+
90+
- **Platform:** GitHub Pages
91+
- **URL:** https://ofriw.github.io/AI-Coding-Course/
92+
- **Trigger:** Automatic on push to main branch
93+
- **Base URL:** `/AI-Coding-Course/`

‎website/docs/CLAUDE.md‎

Lines changed: 232 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,232 @@
1+
# Course Content - Writing Standards
2+
3+
## Target Audience
4+
5+
**Senior Software Engineers** with significant professional experience:
6+
7+
- 3+ years in production environments
8+
- Solid understanding of data structures, algorithms, design patterns
9+
- Experience with system design and architectural decisions
10+
- Familiar with CI/CD, testing, deployment workflows
11+
12+
**NOT beginners** - Avoid basic programming tutorials and introductory concepts.
13+
14+
## Writing Style & Tone
15+
16+
### Voice
17+
18+
**Coworker-level communication** - Talk to peers, not students
19+
20+
- Direct and concise
21+
- Professional but conversational
22+
- Assume competence and intelligence
23+
- Skip obvious explanations
24+
25+
### Avoid
26+
27+
- Marketing language and hype ("revolutionary", "game-changing")
28+
- Excessive hand-holding or patronizing tone
29+
- Basic programming tutorials (unless specifically comparing AI-assisted vs traditional)
30+
- Filler content or unnecessary preambles
31+
- Over-explaining fundamental concepts
32+
33+
### Embrace
34+
35+
- Production-focused examples
36+
- Real-world scenarios and trade-offs
37+
- Architectural considerations
38+
- Security, performance, and scalability implications
39+
- Practical, actionable insights
40+
41+
## Content Structure
42+
43+
### Module Organization
44+
45+
Each module follows this pattern:
46+
47+
```
48+
module-name/
49+
├── index.md # Module overview and objectives
50+
└── lesson-X-topic.md # Individual lessons
51+
```
52+
53+
### Lesson Format (MDX)
54+
55+
Every lesson must include:
56+
57+
```mdx
58+
---
59+
title: 'Lesson Title'
60+
sidebar_position: X
61+
---
62+
63+
## Learning Objectives
64+
65+
- Objective 1 (specific, measurable)
66+
- Objective 2
67+
- Objective 3
68+
69+
## Content
70+
71+
[Main lesson content with examples]
72+
73+
## Hands-On Exercise
74+
75+
[Practical exercise with clear instructions]
76+
77+
## Key Takeaways
78+
79+
- Summary point 1
80+
- Summary point 2
81+
- Summary point 3
82+
```
83+
84+
## Code Examples
85+
86+
### Use Live Code Blocks
87+
88+
Leverage `@docusaurus/theme-live-codeblock` for interactive examples:
89+
90+
```jsx live
91+
function Example() {
92+
return <div>Interactive component</div>;
93+
}
94+
```
95+
96+
### Code Quality Standards
97+
98+
- **All code must compile/run** - Test before including
99+
- Use **TypeScript** where applicable for type safety
100+
- Include **realistic examples** - No foo/bar unless demonstrating concepts
101+
- Show **production patterns** - Error handling, validation, edge cases
102+
- **Comment judiciously** - Only when intent isn't obvious
103+
104+
### Example Characteristics
105+
106+
- **Relevant** - Directly supports the learning objective
107+
- **Minimal** - Just enough code to demonstrate the point
108+
- **Practical** - Based on real-world scenarios
109+
- **Complete** - Include necessary imports and context
110+
111+
## MDX & Markdown Guidelines
112+
113+
### Frontmatter (Required)
114+
115+
```yaml
116+
---
117+
title: 'Clear, Descriptive Title'
118+
sidebar_position: N
119+
---
120+
```
121+
122+
### Headings Hierarchy
123+
124+
- `#` - Page title (auto-generated from frontmatter)
125+
- `##` - Major sections
126+
- `###` - Subsections
127+
- `####` - Avoid deeper nesting
128+
129+
### Admonitions for Important Points
130+
131+
```markdown
132+
:::tip Production Tip
133+
Use this pattern for better performance in production
134+
:::
135+
136+
:::warning Security Consideration
137+
Never expose API keys in client-side code
138+
:::
139+
140+
:::info Context
141+
This approach is preferred in TypeScript projects
142+
:::
143+
```
144+
145+
## Learning Objectives
146+
147+
### Characteristics of Good Objectives
148+
149+
- **Specific** - Clear, well-defined outcome
150+
- **Measurable** - Can verify if achieved
151+
- **Actionable** - Describes what learner will DO
152+
- **Relevant** - Aligned with module goals
153+
- **Time-bound** - Achievable within lesson scope
154+
155+
### Examples
156+
157+
**Good:**
158+
159+
- "Implement effective prompt patterns for code refactoring tasks"
160+
- "Evaluate trade-offs between different AI coding assistants for your workflow"
161+
- "Design a secure architecture leveraging AI for code generation"
162+
163+
**Bad:**
164+
165+
- "Understand AI coding assistants" (too vague)
166+
- "Learn about prompting" (not measurable)
167+
- "Become an expert" (not specific or time-bound)
168+
169+
## Hands-On Exercises
170+
171+
### Exercise Guidelines
172+
173+
- **Real-world context** - Scenarios engineers actually face
174+
- **Clear instructions** - What to do, expected outcome
175+
- **Appropriate difficulty** - Challenging but achievable
176+
- **Multiple paths** - Allow different valid approaches
177+
- **Extension opportunities** - Bonus challenges for faster learners
178+
179+
### Example Exercise Structure
180+
181+
```markdown
182+
## Hands-On Exercise: Prompt-Driven Refactoring
183+
184+
**Scenario:** You have a legacy Node.js API with poor error handling...
185+
186+
**Your Task:**
187+
188+
1. Analyze the code structure
189+
2. Craft a prompt that guides the AI to refactor with:
190+
- Proper error handling middleware
191+
- Validation at API boundaries
192+
- Consistent error response format
193+
3. Evaluate the AI-generated solution
194+
4. Iterate based on issues found
195+
196+
**Expected Outcome:** Production-ready error handling that follows REST best practices
197+
198+
**Bonus Challenge:** Add OpenTelemetry tracing to the refactored code
199+
```
200+
201+
## Content Dependencies
202+
203+
### Prerequisites
204+
205+
Each lesson should reference prerequisites when needed:
206+
207+
```markdown
208+
**Prerequisites:**
209+
210+
- Module 1: Fundamentals (all lessons)
211+
- Understanding of REST API design
212+
```
213+
214+
### Progressive Disclosure
215+
216+
- Build on previous concepts
217+
- Reference earlier examples when relevant
218+
- Link to related lessons: `[See Lesson 2](../fundamentals/lesson-2-mental-models.md)`
219+
220+
## Quality Checklist
221+
222+
Before committing a lesson, verify:
223+
224+
- [ ] Target audience appropriate (senior engineers)
225+
- [ ] Tone is coworker-level, not tutorial-style
226+
- [ ] Learning objectives are specific and measurable
227+
- [ ] Code examples compile and run
228+
- [ ] Examples demonstrate production patterns
229+
- [ ] Hands-on exercise is practical and relevant
230+
- [ ] No marketing fluff or hype
231+
- [ ] Frontmatter is complete and correct
232+
- [ ] MDX syntax is valid

0 commit comments

Comments
 (0)