Skip to content

Commit c7222ce

Browse files
EficodeRjpaltEficodeRjpalt
committed
Fix exercise schema
1 parent ef63f31 commit c7222ce

File tree

1 file changed

+73
-51
lines changed

1 file changed

+73
-51
lines changed

‎challenges/hangperson/hangperson_exercises.md

+73-51
Original file line numberDiff line numberDiff line change
@@ -7,7 +7,7 @@
77
**Key Customization Mechanisms:**
88

99
* **Workspace Instructions (`.github/copilot-instructions.md`):** General project context.
10-
* **Custom Instructions (VS Code Settings / Files):** Specific guidelines for code generation, test generation, etc.
10+
* **Custom Instructions (VS Code Settings / Files):** Specific guidelines for code generation, test generation, etc., configured via `settings.json` often by referencing external `.md` instruction files.
1111
* **Reusable Prompts (`*.prompt.md`):** Parameterized instructions for common, limited-scope tasks.
1212
* **Agent Workflow Instructions (Separate `.md` File):** Detailed, multi-step instructions for complex agent tasks.
1313

@@ -175,67 +175,89 @@
175175
4. Save the file.
176176
5. **Verification (Optional):** Ask Copilot Chat `@workspace What Java version is this project using?` and see if it correctly answers "1.8".
177177
178-
### Exercise 3.2: Define Custom Code Generation Instructions
178+
### Exercise 3.2: Define Custom Code Generation Instructions (via File Reference)
179179
180-
* **Purpose:** To guide Copilot towards generating code that meets specific quality standards, especially for error handling and style.
181-
* **Aim:** Add custom instructions for Java code generation in workspace `settings.json`.
180+
* **Purpose:** To guide Copilot towards generating code that meets specific quality standards, especially for error handling and style, using a referenced instruction file.
181+
* **Aim:** Create a `.md` instruction file for Java code generation guidelines and reference it in workspace `settings.json`.
182182
* **Steps:**
183-
1. Open Workspace Settings (JSON) (`Cmd+Shift+P` / `Ctrl+Shift+P` -> `Preferences: Open Workspace Settings (JSON)`).
184-
2. Add/modify the `github.copilot.editor.instructions` (or similar) section:
183+
1. **Create Instruction File:**
184+
* Create a folder `.vscode` in your workspace root if it doesn't exist.
185+
* Inside `.vscode`, create a file named `copilot_codegen_java_instructions.md`.
186+
* Add the following content to this new file:
187+
```markdown
188+
## Java Code Generation Guidelines (HangpersonApp)
189+
190+
- **Error Handling:**
191+
- For user input (e.g., reading guesses), handle potential exceptions gracefully (e.g., invalid format). Inform the user and prompt again.
192+
- For file I/O (reading word lists), use try-with-resources and catch specific IOExceptions. Propagate errors appropriately (e.g., throw a custom exception or return an empty list). Log errors using SLF4j if available, otherwise System.err.
193+
- **Style:**
194+
- Keep methods relatively short and focused on a single responsibility.
195+
- Add comments explaining non-obvious logic.
196+
- Adhere to Java 1.8 syntax compatibility.
197+
```
198+
* Save `copilot_codegen_java_instructions.md`.
199+
2. **Open Workspace Settings (JSON):** Use the Command Palette (`Cmd+Shift+P` / `Ctrl+Shift+P`) and search for `Preferences: Open Workspace Settings (JSON)`.
200+
3. **Reference Instruction File:** Add or modify the relevant setting for code generation instructions (e.g., `github.copilot.editor.instructions` or `github.copilot.chat.codeGeneration.instructions` - check documentation for the exact key name as it might evolve). Reference the file you created:
185201
```json
186202
{
187203
// ... other settings ...
188-
"github.copilot.editor.instructions": {
189-
"language": {
190-
"java": {
191-
"content": [
192-
"## Java Code Generation Guidelines (HangpersonApp)",
193-
"- **Error Handling:**",
194-
" - For user input (e.g., reading guesses), handle potential exceptions gracefully (e.g., invalid format). Inform the user and prompt again.",
195-
" - For file I/O (reading word lists), use try-with-resources and catch specific IOExceptions. Propagate errors appropriately (e.g., throw a custom exception or return an empty list). Log errors using SLF4j if available, otherwise System.err.",
196-
"- **Style:**",
197-
" - Keep methods relatively short and focused on a single responsibility.",
198-
" - Add comments explaining non-obvious logic."
199-
]
200-
// Or reference a file: "uri": "file:///${workspaceFolder}/.vscode/copilot_codegen_instructions.md"
201-
}
204+
// Example using hypothetical 'github.copilot.chat.codeGeneration.instructions'
205+
"github.copilot.chat.codeGeneration.instructions": [
206+
{
207+
"file": ".vscode/copilot_codegen_java_instructions.md"
208+
// You could add more { "text": "..." } or { "file": "..." } entries here
202209
}
203-
}
210+
],
211+
// Example using hypothetical 'github.copilot.editor.instructions'
212+
// "github.copilot.editor.instructions": {
213+
// "language": { // Note: This language nesting might not be supported per latest schema,
214+
// // prefer the array approach above if possible.
215+
// "java": {
216+
// "uri": "file:///${workspaceFolder}/.vscode/copilot_codegen_java_instructions.md"
217+
// }
218+
// }
219+
// }
204220
// ... other settings ...
205221
}
206222
```
207-
3. Save `settings.json`.
223+
*Choose the setting key that best matches the feature you want to influence (general chat generation vs. inline editor suggestions). The array format (`github.copilot.chat.codeGeneration.instructions` example) is generally more flexible.*
224+
4. Save `settings.json`.
225+
5. **Verification:** Perform the verification steps from the previous version of this exercise (asking Copilot to generate code involving potential I/O) and check if the output adheres to the rules defined in your `.md` file.
208226
209-
### Exercise 3.3: Define Custom Test Generation Instructions
227+
### Exercise 3.3: Define Custom Test Generation Instructions (via File Reference)
210228
211-
* **Purpose:** To ensure generated unit tests follow consistent standards.
212-
* **Aim:** Add custom instructions for Java test generation in workspace `settings.json`.
229+
* **Purpose:** To ensure generated unit tests follow consistent standards using a referenced instruction file.
230+
* **Aim:** Create a `.md` instruction file for Java test generation guidelines and reference it in workspace `settings.json`.
213231
* **Steps:**
214-
1. Open Workspace Settings (JSON).
215-
2. Add/modify the relevant setting for test generation (e.g., `github.copilot.tests.instructions` - check actual key):
232+
1. **Create Instruction File:**
233+
* Inside the `.vscode` folder, create a file named `copilot_testgen_java_instructions.md`.
234+
* Add the following content:
235+
```markdown
236+
## Java Test Generation Guidelines (HangpersonApp)
237+
238+
- **Framework:** Use JUnit 5 (`org.junit.jupiter.api`).
239+
- **Assertions:** Use standard JUnit 5 assertions (`org.junit.jupiter.api.Assertions.*`).
240+
- **Naming:** Use descriptive names, e.g., `testMethodName_WithSpecificInput_ShouldReturnExpected`.
241+
- **Setup/Teardown:** Use `@BeforeEach` / `@AfterEach` where appropriate.
242+
- **Mocking:** Use Mockito if dependencies need mocking (though initial tests might not require it).
243+
- **Structure:** Include clear Arrange, Act, Assert sections commented as `// Arrange`, `// Act`, `// Assert`.
244+
```
245+
* Save `copilot_testgen_java_instructions.md`.
246+
2. **Open Workspace Settings (JSON).**
247+
3. **Reference Instruction File:** Add or modify the relevant setting for test generation instructions (e.g., `github.copilot.tests.instructions` - check documentation for the exact key).
216248
```json
217249
{
218250
// ... other settings ...
219-
"github.copilot.tests.instructions": { // Hypothetical key
220-
"language": {
221-
"java": {
222-
"content": [
223-
"## Java Test Generation Guidelines (HangpersonApp)",
224-
"- **Framework:** Use JUnit 5 (`org.junit.jupiter.api`).",
225-
"- **Assertions:** Use standard JUnit 5 assertions (`org.junit.jupiter.api.Assertions.*`).",
226-
"- **Naming:** Use descriptive names, e.g., `testMethodName_WithSpecificInput_ShouldReturnExpected`.",
227-
"- **Setup/Teardown:** Use `@BeforeEach` / `@AfterEach` where appropriate.",
228-
"- **Mocking:** Use Mockito if dependencies need mocking (though initial tests might not require it).",
229-
"- **Structure:** Include clear Arrange, Act, Assert sections commented as `// Arrange`, `// Act`, `// Assert`."
230-
]
231-
// Or reference a file: "uri": "file:///${workspaceFolder}/.vscode/copilot_testgen_instructions.md"
232-
}
233-
}
234-
}
251+
"github.copilot.tests.instructions": [ // Hypothetical key, check actual setting name
252+
{
253+
"file": ".vscode/copilot_testgen_java_instructions.md"
254+
}
255+
]
235256
// ... other settings ...
236257
}
237258
```
238-
3. Save `settings.json`.
259+
4. Save `settings.json`.
260+
5. **Verification:** Perform the verification steps from the previous version of this exercise (using `/tests` command) and check if the generated tests adhere to the rules defined in your `.md` file.
239261
240262
---
241263
@@ -289,7 +311,7 @@
289311
# AI Agent Workflow: Implement Hangperson Core Logic
290312
291313
## System Prompt
292-
You are a Java developer implementing the core logic for a Hangperson game based on a specification. Adhere strictly to project standards (Java 1.8, JUnit 5, custom instructions for error handling/logging defined in settings, context from `.github/copilot-instructions.md`). Focus on creating the structure and basic logic flow.
314+
You are a Java developer implementing the core logic for a Hangperson game based on a specification. Adhere strictly to project standards (Java 1.8, JUnit 5, custom instructions for error handling/logging defined in referenced files, context from `.github/copilot-instructions.md`). Focus on creating the structure and basic logic flow.
293315
294316
## Workflow
295317
1. **Analyze Spec:** Read the provided game specification (`#specFile`).
@@ -304,7 +326,7 @@
304326
* Process the guess (check if valid, update `GameState`).
305327
* Check for win/loss condition.
306328
* Handle basic user input errors according to custom instructions.
307-
6. **Adhere to Standards:** Ensure generated code follows Java 1.8 syntax, uses specified logging/error handling patterns, and includes basic Javadoc/comments.
329+
6. **Adhere to Standards:** Ensure generated code follows Java 1.8 syntax, uses specified logging/error handling patterns from referenced instruction files, and includes basic Javadoc/comments.
308330
7. **Report:** List files created/modified and note areas needing further implementation (e.g., actual user input loop in `App.java`, file reading for words, drawing the hangman).
309331
310332
**DO NOT implement the full user interface loop in `App.java` yet. Focus on the core classes and logic.**
@@ -328,7 +350,7 @@
328350
*(Adjust invocation based on actual Copilot Agent capabilities)*
329351
3. **Review Generated Code:** Examine the created files (`GameEngine.java`, `GameState.java`, `WordSource.java`).
330352
* Does the structure match the plan?
331-
* Does the error handling (if any generated yet) match the custom instructions?
353+
* Does the error handling (if any generated yet) match the custom instructions defined in your `.vscode/*.md` files?
332354
* Is the logic generally correct based on the spec?
333355
4. **Refine (Example):**
334356
* Maybe the initial guess processing logic in `GameEngine` is too complex. Select that method.
@@ -347,13 +369,13 @@
347369
### Exercise 5.1: Generate Tests for Game Logic
348370
349371
* **Purpose:** To create unit tests for the core game logic classes.
350-
* **Aim:** Use the `/tests` command with the active custom test generation instructions to test `GameState` and potentially parts of `GameEngine`.
372+
* **Aim:** Use the `/tests` command with the active custom test generation instructions (referenced via `settings.json`) to test `GameState` and potentially parts of `GameEngine`.
351373
* **Steps:**
352374
1. Open `GameState.java` (or the file created by the agent in Exercise 4.3).
353375
2. In Copilot Chat, prompt: `# (select GameState.java) /tests Generate JUnit 5 tests for the public methods of this class (like constructor, addCorrectGuess, addIncorrectGuess, isWon, isLost). Follow the project's test guidelines.`
354376
3. Copilot should create/update `GameStateTest.java`. Review the generated tests:
355377
* Are they JUnit 5?
356-
* Do they use the specified assertion style?
378+
* Do they use the specified assertion style (standard JUnit 5)?
357379
* Do names follow the convention?
358380
* Is the Arrange/Act/Assert structure clear?
359381
4. *(Optional)* Repeat for testable methods in `GameEngine.java`, mocking dependencies like `WordSource` if necessary: `# (select GameEngine.java) /tests Generate JUnit 5 tests for the processGuess method, mocking dependencies. Follow project test guidelines.`
@@ -370,10 +392,10 @@
370392
### Exercise 6.1: Refine Instructions or Prompts
371393
372394
* **Purpose:** To improve the guidance given to Copilot based on observed results.
373-
* **Aim:** Modify the custom instructions (`settings.json` or `.github/copilot-instructions.md`) or reusable prompts (`*.prompt.md`) to address any shortcomings noticed during implementation or testing.
395+
* **Aim:** Modify the custom instructions (`.vscode/*.md` files referenced in `settings.json` or `.github/copilot-instructions.md`) or reusable prompts (`*.prompt.md`) to address any shortcomings noticed during implementation or testing.
374396
* **Steps:**
375397
1. Identify an area where Copilot's output didn't fully meet expectations (e.g., error handling wasn't robust enough, test naming was inconsistent despite instructions).
376-
2. Refine the relevant instruction file or prompt file to be more specific or clear.
398+
2. Refine the relevant instruction file (`.md`) or prompt file (`.prompt.md`) to be more specific or clear.
377399
3. Re-run a relevant generation task (e.g., ask Copilot to regenerate a specific method or test) and see if the output improves.
378400
379401
### Exercise 6.2: Implement File-Based Word Source

0 commit comments

Comments
 (0)