Guide to using copilot-instructions.md in kimu-core

This guide explains what the copilot-instructions.md file is, how to integrate it into the kimu-core project, how it is used by AI agents (such as GitHub Copilot), and best practices to keep it effective.

What is copilot-instructions.md

copilot-instructions.md is an instructions file located in the .github folder of the kimu-core project. It contains rules, conventions, examples, and best practices that guide Copilot and other AI agents in generating code that complies with the framework standards.

Purpose of the file

• Provide an authoritative source of rules and conventions for kimu-core development.
• Improve the quality and consistency of code generated by AI agents.
• Facilitate onboarding of new contributors.

Where to place it

The file must be placed in .github/copilot-instructions.md at the root of the kimu-core project.

How Copilot and AI agents use it

• Copilot and AI agents automatically read the file if present in the .github folder.
• The instructions are applied during code generation, suggestions, and refactoring.
• You can mention the file in Copilot requests to get more precise results (e.g., "Follow the rules in copilot-instructions.md").

Best practices for maintenance

• Regularly update the file with new rules, examples, and conventions.
• Document every new feature, pattern, or important change.
• Keep the file clear, concise, and well-structured.
• Link other rule files such as CODE_GUIDELINES.md, CONTRIBUTING.md, etc.

Usage examples

"Create a new extension following the rules in copilot-instructions.md." "How do you integrate Three.js according to copilot-instructions.md?"

FAQ

Q: Do I need to manually train Copilot? A: No, just make sure the file is present and up to date. Copilot uses it automatically.

Q: Can I use the file with other AI agents? A: Yes, any AI agent that supports instruction files can read and apply the rules.

Q: Where can I find practical examples? A: In the file itself and in the extension documentation.

Troubleshooting

• If Copilot does not follow the rules, check that the file is up to date and well-structured.
• Specify in your requests that it should follow the instructions in the file.

Useful resources

---

Recommended structure for copilot-instructions.md

Organize the file into clear, easily navigable sections:

• Introduction and purpose
• Project structure
• Development rules and conventions
• Practical examples
• FAQ and troubleshooting
• Extension checklist
• Glossary

How to write effective examples

• Use clear, commented TypeScript code.
• Show real use cases and recurring patterns.
• Include snippets for extensions, data binding, external library integration.

Workflow integration

• Include file checks in code reviews.
• Mention the file in pull requests and technical discussions.
• Use the file for onboarding new contributors.
• You can integrate compliance checks via CI/CD scripts.

Practical benefits

• Reduces errors and inconsistencies in generated code.
• Facilitates collaboration between developers and AI agents.
• Improves project quality and maintainability.

Common mistakes to avoid

• Outdated or incomplete file.
• Unclear or non-compliant examples.
• Missing links to other rule files.

How to propose changes

• Open an issue or pull request in the kimu-core repository.
• Clearly explain the reason for the change.
• Also update related documentation if necessary.

External resources

• GitHub Copilot Documentation
• Best practices for AI agents

Glossary

• Copilot Agent: AI assistant that generates code following the file's instructions.
• Extension: Custom module that adds functionality to kimu-core.
• Data Binding: Reactive link between data and UI.
• Checklist: List of steps to follow to create a new extension.
• CI/CD: Continuous integration and deployment, useful for automating quality checks.

---

Update this guide whenever you change the rules or conventions in the copilot-instructions.md file.