Skip to content

Commit 7570966

Browse files
committed
Address review comments: remove fluff from AI guidelines
- Streamline ai-usage-guidelines.md to keep only verbatim key points - Remove duplicate section headers - Remove "Key requirements" section from AGENTS.md to prevent staleness https://claude.ai/code/session_01CAnhr6MGdgQghH43KZYLpE
1 parent 81fe375 commit 7570966

2 files changed

Lines changed: 1 addition & 48 deletions

File tree

AGENTS.md

Lines changed: 0 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -3,9 +3,3 @@
33
AI agents contributing to this repository must read and follow the guidelines in the developer documentation:
44

55
[Guidelines for AI-Assisted Development](doc/dev/ai-usage-guidelines.md)
6-
7-
Key requirements:
8-
- A human manager must review and fully understand all contributed code
9-
- All commits must include the @username of the human manager
10-
- Pull requests require human manager self-review before peer review
11-
- Human manager effort must exceed effort requested from peer reviewers

doc/dev/ai-usage-guidelines.md

Lines changed: 1 addition & 42 deletions
Original file line numberDiff line numberDiff line change
@@ -1,64 +1,23 @@
11
# Guidelines for AI-Assisted Development
22

3-
This document provides guidelines for using AI tools (such as large language models, code generation assistants, and similar technologies) when contributing to the Empirical project.
4-
53
## Guiding Principle
64

75
**A human must ultimately take responsibility for all aspects of library code.**
86

9-
AI tools can be valuable aids in software development, but they do not replace human judgment, understanding, or accountability.
107
All code contributed to Empirical, regardless of how it was generated, must meet the same standards of quality, correctness, and maintainability.
118

12-
## Guidelines
13-
149
### 1. Human Manager Responsibility
1510

16-
The human manager (i.e., the contributor submitting the code) is responsible for reviewing and fully understanding all contributed code.
17-
18-
- You must be able to explain what the code does and why it works
19-
- You must verify that the code is correct, secure, and follows Empirical's coding standards
20-
- You must ensure the code integrates properly with the existing codebase
21-
- If you cannot fully understand or explain a piece of AI-generated code, do not submit it
11+
The human manager is responsible for reviewing and fully understanding all contributed code.
2212

2313
### 2. Commit Attribution
2414

2515
Commits may be attributed to the AI tool used, but all commit messages should include the `@username` of the human manager.
2616

27-
- This ensures traceability and accountability
28-
- The human manager remains responsible for the commit's contents
29-
- Example commit message format:
30-
```
31-
Add utility function for data processing
32-
33-
Generated with assistance from [AI Tool Name]
34-
Human manager: @username
35-
```
36-
3717
### 3. Pull Request Review Process
3818

3919
Pull requests should go through the usual peer review process, with the human manager completing a pull request code review process first before requesting peer review.
4020

41-
- Before adding the "Merge Ready" label, the human manager must conduct their own thorough review
42-
- Self-review should verify all items in the standard [code review checklist](contribution-guidelines-and-review.md#checklist)
43-
- Only after completing self-review should peer review be requested
44-
- Peer reviewers should be informed if AI tools were used in development
45-
4621
### 4. Effort Balance
4722

4823
The effort contributed by the human manager should exceed the effort requested from peer reviewers.
49-
50-
- The human manager bears the primary burden of ensuring code quality
51-
- Peer reviewers should not be expected to do extensive verification work that the human manager should have done
52-
- If a contribution requires significant review effort, the human manager should put in proportionally more effort to prepare and document the changes
53-
- This includes writing comprehensive tests, documentation, and explanatory comments
54-
55-
## Guidelines
56-
57-
When using AI tools to contribute to Empirical:
58-
59-
1. **Understand** everything you submit
60-
2. **Attribute** AI involvement while maintaining human accountability
61-
3. **Review** your own work thoroughly before requesting peer review
62-
4. **Balance** effort so that you contribute more than you ask of others
63-
64-
Following these guidelines ensures that AI tools enhance rather than undermine the quality and integrity of the Empirical codebase.

0 commit comments

Comments
 (0)