diff --git a/claude-code/.claude/commands/implement-gh-issue.md b/claude-code/.claude/commands/implement-gh-issue.md new file mode 100644 index 0000000..cb82c18 --- /dev/null +++ b/claude-code/.claude/commands/implement-gh-issue.md @@ -0,0 +1,59 @@ +# Implement GitHub Issue + +Implement a feature based on a GitHub issue implementation plan. + +## Issue: $ARGUMENTS + +## Execution process + +1. **Load the implementation plan** + +- Look for the implementation plan in `docs/implementation-plans/gh-issue-{issue-number-or-name}.md` +- If no plan exists, inform the user they need to run `/plan-gh-issue` first +- Read and understand the context and requirements from the plan +- Follow all instructions in the implementation plan document +- Ensure you have all needed context to implement the requirements fully +- Do more web and code base search as necessary + +1. **Plan the implementation** + +- Think before you execute the plan. Create a comprehensive plan addressing all requirements. +- Break down complex tasks into smaller, manageable steps using your TODO tools. +- Use the TodoWrite tool to create and track your implementation plan. +- Identify implementation patterns from existing code to follow as specified in the plan. + +1. **Execute the plan** + +- Implement the requirements from the implementation plan document +- Write the code necessary following the architectural patterns identified +- Reference the specific files and examples mentioned in the plan +- Follow the ordered task list provided in the implementation blueprint + +1. **Validate** + +- Run each validation gate specified in the plan +- Execute test commands, linting, and quality checks as documented +- Fix any failures +- Re-run until all validation gates pass + +1. **Complete** + +- Ensure all checklist items from the plan are done +- Run final validation suite +- Report completion status +- Read the implementation plan again to ensure you've implemented everything + +1. **Reference the implementation plan** + +- You can always reference the implementation plan document again +- The plan contains all the research and context needed for successful implementation + +## Usage + +Use this command by providing the same identifier used in `/plan-gh-issue`: + +- `/implement-gh-issue 123` (for issue number 123) +- `/implement-gh-issue feature-name` (for issues saved by name) +- `/implement-gh-issue https://github.com/owner/repo/issues/123` (will extract issue number) + +The command will automatically locate the corresponding implementation plan file. diff --git a/claude-code/.claude/commands/plan-gh-issue.md b/claude-code/.claude/commands/plan-gh-issue.md new file mode 100644 index 0000000..337dd18 --- /dev/null +++ b/claude-code/.claude/commands/plan-gh-issue.md @@ -0,0 +1,92 @@ +# Generate Implementation Plan from GitHub Issue + +## Issue: $ARGUMENTS + +Generate a complete implementation plan for a GitHub issue based on thorough +research. **Start by researching the issue** from the provided GitHub issue URL +or issue description to understand what needs to be done, how examples provide +help, and any other considerations. + +**Important**: The implementation plan will be used by another Claude Code agent for +implementation. Include all necessary context since the implementing agent only gets +access to what you document here. The agent has access to the codebase and web search +capabilities, so include specific URLs and code references. + +## Research Process + +### 0. Issue Analysis + +- Research the GitHub issue using web search if URL provided, or analyze the provided issue description +- Extract the feature description, examples, documentation references, and considerations +- Use this as the foundation for all subsequent research + +### 1. Codebase Analysis + +- Search for similar patterns/features in the workspace +- Identify files to reference in the requirements document +- Note existing conventions and architectural patterns to follow +- Check test patterns and validation approaches + +### 2. External Research + +- Find relevant library documentation using web search (include specific URLs) +- Look for implementation examples and best practices +- Identify common pitfalls and gotchas +- Research integration patterns and similar implementations + +### 3. Context Gathering + +- Identify specific patterns to mirror and their locations +- Document integration requirements and dependencies +- Note any version-specific considerations + +## Requirements Document Structure + +### Critical Context to Include + +- **Documentation URLs**: Link to specific sections found through web search +- **Code Examples**: Real snippets from the codebase showing patterns to follow +- **Architectural Patterns**: Existing approaches that should be mirrored +- **Integration Points**: How this feature connects with existing code +- **Gotchas**: Library quirks, version issues, common mistakes + +### Implementation Blueprint + +- Start with high-level approach and pseudocode +- Reference specific files for patterns to follow +- Include comprehensive error handling strategies +- Provide ordered task list for step-by-step implementation +- Document validation and testing approach + +### Validation Gates + +Define specific commands and criteria for validation: + +- Test commands (e.g., `npm test`, `dotnet test`, `python -m pytest`) +- Linting and code quality checks +- Performance benchmarks if applicable +- Integration test requirements + +## Output Requirements + +Save the implementation plan as `docs/implementation-plans/gh-issue-{issue-number-or-name}.md`. +The plan should be structured, clear, and detailed enough for another Claude Code agent +to implement without needing further clarification. + +## Quality Checklist + +Before finishing, verify the requirements include: + +- [ ] All necessary context for autonomous implementation +- [ ] Validation gates that are executable +- [ ] References to existing patterns and conventions +- [ ] Clear, ordered implementation path +- [ ] Comprehensive error handling documentation +- [ ] Main flow and alternate scenarios covered +- [ ] Specific code examples and file references +- [ ] Research from external sources with URLs + +**Quality Score**: Rate the requirements document on a scale from 1-10 for confidence +in successful single-pass implementation using Claude Code. Explain the score and +suggest improvements if below 8. + diff --git a/claude-code/README.md b/claude-code/README.md index 55031b6..a54074a 100644 --- a/claude-code/README.md +++ b/claude-code/README.md @@ -20,9 +20,10 @@ Then, copy the following files to your project: ```text claude-code/.claude/commands/generate-plan.md # Prompt template to create requirements documents. claude-code/.claude/commands/implement-plan.md # Prompt template to implement requirements. -claude-code/implementation-plans/.gitkeep # Folder to store the requirements documents. +claude-code/docs/implementation-plans/.gitkeep # Folder to store the requirements documents. claude-code/src/.gitkeep # Source folder (optional) claude-code/CLAUDE.md # General instructions for the project +claude-code/TASK.md # The template for the initial feature description ``` If you're using this on a completely new repository I recommend setting up the @@ -45,19 +46,31 @@ CLAUDE.md file. You'll need to provide the following: I recommend writing short and concise instructions for the LLM. This helps keep enough space available in the context window for actual work. -**Tip**: Unsure of what to write in the `CLAUDE.md` file for your project? -You can ask Claude Code to generate the file for you. Use the `/init` +**Tip**: Unsure of what to write in the `CLAUDE.md` file for your project? +You can ask Claude Code to generate the file for you. Use the `/init` command inside Claude Code to get an initial set of instructions based on what your project looks like. -### Writing the work item instructions +### Writing work item instructions -Before you start using Claude Code to write code, you'll need to come up with -an initial set of instructions for the requirements generation. Create a new -file `TASK.md` in the root of the repository with the following content: +After you've configured the instructions for your project you can start to work on +implementing features. I included two methods for this in the repository: + +1. Planning work with Github Issues +2. Planning work with TASK.md on your local computer + +**IMPORTANT:** If you plan to work with Github Issues you need to have [the Github MCP +server](https://docs.anthropic.com/en/docs/claude-code/mcp) or the [Github +CLI](https://cli.github.com/) installed. + +#### Planning work with TASK.md on your local computer + +The process of implementing a feature using the context engineering approach starts with +generating an implementation plan. If you want to work locally without GitHub you can +edit the `TASK.md` file in the root of the repository with the following content: ```text -# Feature +# Feature: @@ -80,31 +93,29 @@ things here that the agent is missing a lot.> I prefer to keep the `TASK.md` file checked in as a reminder to myself of what I need to provide as input for generating requirements. -### Generate a requirements document +#### Generate an implementation plan -After you've created the requirements document, you can start to generate -requirements. Start Claude Code with `claude` and then issue the following -command: +After you've created the work item in `TASK.md`, you can start to generate an implementation plan. +Start Claude Code with `claude` and then issue the following command: ```bash /generate-plan TASK.md ``` -It will take a few minutes for Claude Code to write the full requirements -document. You can continue to iterate on the requirements manually or by -opening Claude Code in the terminal inside VSCode. The agent will automatically -focus on the requirements document when you have it open in VSCode alongside -Claude Code in the built-in terminal. +It will take a few minutes for Claude Code to write the full implementation plan. +You can continue to iterate on the implementation plan file in the same chat session. The generated requirements document will be stored in the `docs/implementation-plans` directory. -Once you're happy with the requirements, you can start to generate code. +Once you're happy with the plan, you can start to generate code. If you find that +the generated plan gets too large, you can split the file into multiple separate +planning documents. You can even ask Claude Code to do this for you. -### Generating code +#### Generating code -Use the following command in the Claude Code terminal to kick off the -implementation of the generated requirements document. +Open the generated implementation plan, and use the following command in the Claude Code +terminal to kick off the implementation of the generated requirements document. ```bash /implement-plan docs/implementation-plans/ @@ -113,15 +124,69 @@ implementation of the generated requirements document. This will again take a few minutes to complete. This is a great time to get hydrated, take a bio break, and talk to a colleague. +### Planning work with Github Issues + +If you prefer to use Github Issues as the basis for your feature implementation instead +of the local `TASK.md` file you can use the `/plan-gh-issue "{issue-number}"` +prompt in the Copilot Chat Window. Replace `{issue-number}` with the actual issue number. + +The `plan-gh-issue` prompt relies on the content of the referenced issue on GitHub. You +also need to have [the Github MCP +Server](https://docs.anthropic.com/en/docs/claude-code/mcp) installed. Alternatively +Claude Code will use the [Github CLI](https://cli.github.com/) to access your repository +information. + +**Tip:** If you don't know the issue number, use the issue title. Claude Code will find +the issue in your Github repository. + +During testing I've found that creating a detailed issue description is important to get +the best results. I therefore recommend that you write issues following a similar +structure to the one displayed below. + +```text + + +## Examples + + + +## Documentation + + + +## Other considerations + + +``` + +Make sure to give the issue a clear title to help Claude Code come up with the +correct implementation plan. + +When you execute the `/plan-gh-issue "{issue-number}"` prompt, the implementation plan +will be posted as comment to your issue so you can edit and refine the plan on Github. +As with all prompts, you can continue to iterate in the chat window. + +After generating the plan, you can implement the GitHub issue with the prompt +`/implement-gh-issue "{issue-number}"`. Replace `{issue-number}` with the actual +issue number. + ### Reviewing code Once you have the code it's important to verify that the code is to your liking. -You can do this by [configuring Claude Code as a -PR reviewer](https://docs.anthropic.com/en/docs/claude-code/github-actions). +You can ask Claude Code to review the code for you. I recommend manually reviewing your code because the AI can't catch every problem in your code. +**Note:** The AI doesn't always produce the output you want. At least not completely. +This is okay! Just continue to iterate in the chat session. If you're working on +something really large, you can also commit the changes and +[rebase](https://git-scm.com/book/en/v2/Git-Tools-Rewriting-History) them later to clean +up the history so you can go back and forth. + ## Tips and tricks ### :bulb: Break up tasks into smaller pieces @@ -166,3 +231,13 @@ This template uses a single `CLAUDE.md` file in the root but you can add more detail by putting a `CLAUDE.md` file within your project directories. For example, you can provide specific instructions for your web frontend by placing a `CLAUDE.md` in the web frontend directory. + +### :bulb: Not using GitHub? Don't worry, this works with other source control providers too + +I know that not everyone is using GitHub. Just modify the prompt template a bit, and +install the correct MCP server. You may need to change the tool configuration a bit in +the prompt. Refer to the [Claude Code MCP Server +Documentation](https://docs.anthropic.com/en/docs/claude-code/mcp) for more information. + +- Gitlab MCP server: https://hub.docker.com/r/mcp/gitlab +- Azure DevOps MCP server: https://github.com/microsoft/azure-devops-mcp \ No newline at end of file