Skip to content

Commit eeede58

Browse files
BionicCodeBionicCode
authored
Enhance AGENTS.md with detailed review guidelines
Expanded the AGENTS.md file to include general engineering rules, review mission details, primary invariants, output format requirements, review depth rules, and review style guidelines.
1 parent a39b548 commit eeede58

File tree

1 file changed

+99
-25
lines changed

1 file changed

+99
-25
lines changed

‎AGENTS.md‎

Lines changed: 99 additions & 25 deletions
Original file line numberDiff line numberDiff line change
@@ -1,30 +1,104 @@
1-
If user prompt only contains "<review>", consider it an instructions placeholder for the [REVIEW MISSION (default)](#review-mission-default) section which serves as the real task input:
1+
# GENERAL ENGINEERING RULES
2+
- Favor correctness, readability, testability, and explicit domain boundaries over minimizing type count.
3+
- Do not let external SDK/runtime types leak into domain models unless explicitly requested.
4+
- Prefer replacing structurally wrong draft designs over patching them in place.
5+
- When a task is architectural, propose a plan first before writing code.
6+
7+
If the user prompt is exactly "<review>", treat it as a placeholder that expands to the task defined in the [REVIEW MISSION (default)](#review-mission-default) section below.
8+
9+
User prompt instructions always override this file.
210

311
# REVIEW MISSION (default)
4-
Goal: Perform a deep, call-tree-based review focused on correctness of reflection identity/caching.
5-
Default entry point(s):
6-
- Start at: public API of SymbolReflectionInfoCache and SymbolReflectionInfoCacheKey
7-
- Trace: Full call tree.
12+
Goal: Perform a deep, call-tree-based code review focused on correctness of reflection identity and caching behavior.
13+
14+
Default entry points:
15+
- Start at the public API surface of:
16+
- `SymbolReflectionInfoCache`
17+
- `SymbolReflectionInfoCacheKey`
18+
- Trace the full reachable call tree from those entry points as far as repository context allows.
819

9-
If the user prompt specifies a different entry point or path, follow the user prompt (user prompt overrides AGENTS.md).
20+
If the user specifies different entry points, files, methods, or paths, follow the user prompt instead.
1021

1122
# PRIMARY INVARIANTS (Definition of Done)
12-
I should be able to trust that:
13-
1) Indexer parameters normalize to a stable identity across retrieval paths
14-
2) Parameter cache keys are consistent and won’t split/duplicate entries depending on acquisition path
15-
3) TypeData caching makes the hot path reflection-free after warmup
16-
4) Explicit interface accessors are handled correctly (no name-heuristic pitfalls)
17-
18-
# OUTPUT FORMAT I WANT
19-
- Organize by file headers.
20-
- Use filename + 1-based line references like [L123].
21-
- Findings tagged: [ERROR]/[BUG]/[SECURITY]/[PERF]/[DESIGN]/[API]/[DOCS]/[TEST]/[STYLE]/[RISK].
22-
- After findings: “Coverage / Call-tree traversal depth” (which paths you traced, and where you had to stop due to missing context).
23-
24-
# REVIEW DEPTH RULES
25-
- Always include a short “Call-tree” section showing the traced chain (at least: method A -> method B -> method C).
26-
- If you cannot fully trace due to missing files/context, stop and explicitly say where you stopped.
27-
28-
# OPTIONAL: COMMANDS / EXECUTION
29-
- Do not run build/tests unless explicitly requested by the user.
30-
- Prefer static reasoning + code inspection.
23+
A correct implementation should satisfy all of the following:
24+
25+
1. Indexer parameters normalize to a stable identity across all retrieval paths.
26+
2. Parameter cache keys are consistent and do not split or duplicate entries depending on acquisition path.
27+
3. `TypeData` caching makes the hot path reflection-free after warmup.
28+
4. Explicit interface accessors are handled correctly without brittle name-based heuristics.
29+
30+
# REVIEW PRIORITIES
31+
Prioritize findings in this order:
32+
1. Correctness
33+
2. Cache identity / consistency
34+
3. Hidden duplication or split-cache risks
35+
4. API contract mismatches
36+
5. Performance on hot paths
37+
6. Maintainability / design clarity
38+
39+
# REQUIRED REVIEW METHOD
40+
- Review by tracing actual call paths, not by isolated file scanning only.
41+
- Start from the selected entry point(s) and follow calls downward until:
42+
- the full relevant path is understood, or
43+
- you hit a boundary caused by missing files, generated code, external dependencies, or insufficient context.
44+
- Prefer evidence-based findings over speculative concerns.
45+
- Do not infer behavior from naming alone when call tracing can verify it.
46+
47+
# OUTPUT FORMAT
48+
Organize the review by file.
49+
50+
For each file:
51+
- Use a file header with the filename.
52+
- Use 1-based line references in the format `[L123]`.
53+
- Tag each finding with one primary category:
54+
- `[ERROR]`
55+
- `[BUG]`
56+
- `[SECURITY]`
57+
- `[PERF]`
58+
- `[DESIGN]`
59+
- `[API]`
60+
- `[DOCS]`
61+
- `[TEST]`
62+
- `[STYLE]`
63+
- `[RISK]`
64+
65+
When useful, mention secondary impacts in the explanation, but keep one primary tag per finding.
66+
67+
# REQUIRED SECTIONS IN THE REVIEW
68+
Include these sections in this order:
69+
70+
1. `Scope / Entry Points`
71+
- What you reviewed
72+
- Which entry points were used
73+
74+
2. `Call-tree`
75+
- Show the traced chain(s), for example:
76+
- `MethodA -> MethodB -> MethodC`
77+
- Include enough detail to show how conclusions were reached
78+
79+
3. `Findings`
80+
- Organized by file
81+
- Include line references and category tags
82+
83+
4. `Coverage / Call-tree traversal depth`
84+
- State which paths were fully traced
85+
- State where tracing stopped
86+
- State why tracing stopped (missing file, external dependency, unclear dynamic dispatch, generated code, etc.)
87+
88+
# STOP / UNCERTAINTY RULES
89+
- If you cannot fully verify a path, stop and explicitly say where verification stopped.
90+
- Do not present an assumption as a confirmed defect.
91+
- Distinguish clearly between:
92+
- confirmed issue,
93+
- likely risk,
94+
- unverified suspicion due to missing context.
95+
96+
# OPTIONAL COMMANDS / EXECUTION
97+
- Do not run builds, tests, benchmarks, or other commands unless the user explicitly requests it.
98+
- Prefer static reasoning and code inspection by default.
99+
100+
# REVIEW STYLE
101+
- Be concise but not shallow.
102+
- Focus on actionable findings.
103+
- Prefer robust fixes over minimal patches when the design is structurally unsafe.
104+
- Call out invariant violations explicitly.

0 commit comments

Comments
 (0)