add AGENTS.md #7071
add AGENTS.md #7071
Conversation
Added AGENTS.md with detailed documentation for AI coding agents working on the Condo project, including project overview, monorepo structure, environment setup, code style guidelines, testing patterns, commit conventions, and UI kit usage instructions.
Added comprehensive documentation for handling Semgrep false positives, including format guidelines, common use cases with examples (path traversal, HTTP servers in tests, TLS bypass, dynamic RegExp, unsafe format strings), best practices for nosemgrep comments, and instructions for finding rule IDs.
Fixed code block language from typescript to css for CSS Modules example, updated comment syntax to CSS format, changed class name to kebab-case convention, and added note explaining automatic kebab-case to camelCase conversion in CSS Modules.
AleX83Xpert
added
the
✋🙂 Review please
WalkthroughA new developer guide document AGENTS.md is added to the repository, providing comprehensive documentation on the Condo monorepo structure, environment setup, development workflows, coding standards, testing, linting, commit conventions, architecture patterns, and best practices. Changes
Estimated code review effort🎯 1 (Trivial) | ⏱️ ~5 minutes Suggested reviewers
Pre-merge checks and finishing touches❌ Failed checks (1 inconclusive)
✅ Passed checks (2 passed)
✨ Finishing touches🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 0
🧹 Nitpick comments (3)
AGENTS.md (3)
9-9: Wrap bare URLs in markdown link syntax.AGENTS.md is a simple, open format for guiding coding agents, treating it as a README for agents with context and instructions. Bare URLs in markdown should be wrapped in link syntax for better rendering and readability.
Consider these improvements:
- Line 9: Wrap the repository URL in markdown link syntax:
- **Repository:** [https://github.com/open-condo-software/condo](https://github.com/open-condo-software/condo)
Lines 3 & 753-755, 797: Similar bare URL issues throughout the file should be wrapped in markdown links.
Line 3 (optional): Consider hyphenating compound adjectives for consistency:
"Open-Source property management SaaS platform"when "Open Source" precedes and modifies the noun.Also applies to: 3-3
748-797: Wrap remaining bare URLs in markdown link syntax.Lines 753, 754, 755, and 797 contain bare URLs that should be wrapped in markdown link syntax for consistency and better rendering:
- **Main docs:** [/docs/develop.md](/docs/develop.md), [/docs/contributing.md](/docs/contributing.md), [/docs/deploy.md](/docs/deploy.md) - **Migration guide:** [/docs/migration.md](/docs/migration.md) - **Database upgrade guide:** [/docs/db-upgrade.md](/docs/db-upgrade.md) - **Keystone docs:** [https://github.com/keystonejs/keystone-5](https://github.com/keystonejs/keystone-5) - **Next.js docs:** [https://nextjs.org](https://nextjs.org) - **Apollo docs:** [https://www.apollographql.com](https://www.apollographql.com) - **URL:** [http://localhost:4006/admin/signin](http://localhost:4006/admin/signin)
1-797: Comprehensive, well-structured AGENTS.md that effectively guides AI coding agents.This documentation successfully implements the AGENTS.md standard with thorough coverage of the Condo project structure, setup, development workflows, code style, testing patterns, and best practices. AGENTS.md complements README by containing extra, sometimes detailed context coding agents need: build steps, tests, and conventions.
Strengths:
- Clear, actionable guidance with concrete code examples
- Comprehensive Semgrep exclusion guidelines with real-world scenarios
- Well-organized sections covering all essential aspects
- Practical troubleshooting and common pitfalls (lines 724–730)
- Strong emphasis on UI Kit usage with complete examples
- Testing patterns that emphasize simplicity and actual behavior
Minor items to improve:
- Wrap bare URLs in markdown link syntax (lines 9, 753–755, 797)
- Optional: hyphenate compound adjectives ("Open-Source property management...")
📜 Review details
Configuration used: defaults
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (1)
AGENTS.md
🧰 Additional context used
🧠 Learnings (5)
📚 Learning: 2025-09-17T13:38:39.633Z
Learnt from: SavelevMatthew
Repo: open-condo-software/condo PR: 6645
File: apps/dev-portal-web/domains/common/components/auth/AuthForm.tsx:12-12
Timestamp: 2025-09-17T13:38:39.633Z
Learning: In the condo project, runtime configuration fallbacks for authMethods are handled at the Next.js config level in next.config.ts, where AUTH_METHODS defaults to ['condo'] if not provided via environment variables, ensuring safe destructuring in components that access publicRuntimeConfig.authMethods.
Applied to files:
AGENTS.md
📚 Learning: 2025-09-17T13:39:10.781Z
Learnt from: SavelevMatthew
Repo: open-condo-software/condo PR: 6645
File: apps/dev-portal-web/domains/common/components/auth/LoginForm.tsx:1-3
Timestamp: 2025-09-17T13:39:10.781Z
Learning: In the condo project, authMethods fallback is handled at the Next.js configuration level in next.config.ts with AUTH_METHODS defaulting to '["condo"]' via JSON.parse(conf['AUTH_METHODS'] || '["condo"]'), making direct destructuring of publicRuntimeConfig.authMethods safe without additional guards in components.
Applied to files:
AGENTS.md
📚 Learning: 2025-09-17T13:38:39.633Z
Learnt from: SavelevMatthew
Repo: open-condo-software/condo PR: 6645
File: apps/dev-portal-web/domains/common/components/auth/AuthForm.tsx:12-12
Timestamp: 2025-09-17T13:38:39.633Z
Learning: In the condo project, runtime configuration fallbacks for authMethods are handled at the Next.js config level in next.config.ts, where AUTH_METHODS defaults to ["condo"] via JSON.parse(conf['AUTH_METHODS'] || '["condo"]') if not provided via environment variables, ensuring safe destructuring in components that access publicRuntimeConfig.authMethods.
Applied to files:
AGENTS.md
📚 Learning: 2025-08-04T08:04:46.817Z
Learnt from: SavelevMatthew
Repo: open-condo-software/condo PR: 6472
File: apps/condo/schema.graphql:390-394
Timestamp: 2025-08-04T08:04:46.817Z
Learning: In the condo codebase, the schema.graphql file is auto-generated (codegen) from Keystone 5 schema definitions. Security and access controls are implemented in the actual Keystone schema files (like User.js) using access control properties such as SERVER_CREATE_ONLY_ACCESS, not in the generated GraphQL schema file. When reviewing schema.graphql, consider that field presence doesn't indicate lack of access controls - check the corresponding Keystone schema files for actual security implementation.
Applied to files:
AGENTS.md
📚 Learning: 2025-09-17T13:39:10.781Z
Learnt from: SavelevMatthew
Repo: open-condo-software/condo PR: 6645
File: apps/dev-portal-web/domains/common/components/auth/LoginForm.tsx:1-3
Timestamp: 2025-09-17T13:39:10.781Z
Learning: In the condo project, authMethods fallback is handled at the Next.js configuration level in next.config.ts with AUTH_METHODS defaulting to ["condo"], making direct destructuring of publicRuntimeConfig.authMethods safe without additional guards in components.
Applied to files:
AGENTS.md
🪛 LanguageTool
AGENTS.md
[uncategorized] ~3-~3: If this is a compound adjective that modifies the following noun, use a hyphen.
Context: ...gents working on the Condo project - an Open Source property management SaaS platform. ## ...
(EN_COMPOUND_ADJECTIVE_INTERNAL)
[style] ~351-~351: The words ‘explain’ and ‘explanations’ are quite similar. Consider replacing ‘explain’ with a different word.
Context: ...or) ``` Best practices: - Always explain why the flagged code is safe before t...
(VERB_NOUN_SENT_LEVEL_REP)
[style] ~711-~711: The double modal “needed Run” is nonstandard (only accepted in certain dialects). Consider “to be Run”.
Context: ...nch 2. Make schema changes if needed 3. Run `yarn workspace @app/ makemigrati...
(NEEDS_FIXED)
🪛 markdownlint-cli2 (0.18.1)
AGENTS.md
9-9: Bare URL used
(MD034, no-bare-urls)
753-753: Bare URL used
(MD034, no-bare-urls)
754-754: Bare URL used
(MD034, no-bare-urls)
755-755: Bare URL used
(MD034, no-bare-urls)
797-797: Bare URL used
(MD034, no-bare-urls)
⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (5)
- GitHub Check: Build open-source part (ubuntu-22.04, 24.x, 3.14)
- GitHub Check: Check dependencies integrity (24.x)
- GitHub Check: Semgrep vulnerabilities check
- GitHub Check: Lint source code (24.x)
- GitHub Check: Build Docker Image
🔇 Additional comments (4)
AGENTS.md (4)
301-355: Semgrep exclusion guidelines are excellent.The documentation on lines 301–355 provides comprehensive, practical guidance for Semgrep false-positive suppression with real-world examples and best practices. This is valuable for agents to understand when and how to safely suppress security warnings.
364-400: Commit conventions are clear and practical.The commit message format, types, scopes, and examples are well-documented with concrete, actionable guidance. The inclusion of task number requirements and hotfix exceptions provides clarity for agents and developers.
402-678: UI Kit documentation is comprehensive and well-structured.Real code snippets showing actual style beat paragraphs describing it, demonstrating what good output looks like. This section excellently demonstrates component usage with:
- Clear import patterns and type support
- Real component examples (Button, Table, Modal, Typography)
- Responsive design with hooks
- Color tokens and theming guidance
- Best practices for minimal custom styling
The emphasis on preferring
@open-condo/uicomponents over custom CSS aligns with design system best practices.
706-731: Development workflow and common pitfalls are well-documented.The feature workflow guidance and common pitfalls section (lines 724–730) provide practical, actionable insights—particularly the emphasis on building packages first, running migrations after schema changes, and using correct faker methods.
|
tolmachev21
left a comment
tolmachev21
left a comment
There was a problem hiding this comment.
The only downside is that it needs to be maintained.
| - `@open-condo/ui` - **UI Kit** (recommended for all GUI elements) | ||
| - `@open-condo/icons` - Icon library | ||
| - `@open-condo/*` packages - Core utilities and shared functionality | ||
| - `webhooks` - Webhook functionality |
There was a problem hiding this comment.
This should be also @open-condo
| ## Environment Requirements | ||
|
|
||
| ### Required Software | ||
| - **Node.js:** 22.x (LTS) - Use nvm for local development |
There was a problem hiding this comment.
| - **Node.js:** 22.x (LTS) - Use nvm for local development | |
| - **Node.js:** 24.x (LTS) - Use nvm for local development |
| - **Node.js:** 22.x (LTS) - Use nvm for local development | ||
| - **Yarn:** 3.2.2+ (Berry) | ||
| - **Python:** 3.x (for database migrations) | ||
| - **PostgreSQL:** 16.4+ |
There was a problem hiding this comment.
| - **PostgreSQL:** 16.4+ | |
| - **PostgreSQL:** 16.8+ |
| - **Yarn:** 3.2.2+ (Berry) | ||
| - **Python:** 3.x (for database migrations) | ||
| - **PostgreSQL:** 16.4+ | ||
| - **Redis:** 6.2+ |
|
|
||
| ### Python Packages | ||
| ```bash | ||
| pip install Django psycopg2-binary |
There was a problem hiding this comment.
its better to clone exact versions from werf / docker-compose
| ### Initial Setup | ||
| ```bash | ||
| # 1. Start databases (optional, using Docker) | ||
| docker compose up -d postgresdb redis |
There was a problem hiding this comment.
| docker compose up -d postgresdb redis | |
| docker compose --profile dbs up -d |
| yarn workspace @app/condo migrate:unlock | ||
| ``` | ||
|
|
||
| ### Build Commands |
There was a problem hiding this comment.
Add command to build dependencies build:deps
|
LGTM @coderabbitai suggest, what should we add to agents guide based on your knowledges from previous pull requests |
|
Tip For best results, initiate chat on the files or code changes. 🧩 Analysis chain🏁 Script executed: Length of output: 23917 @SavelevMatthew Great! Based on the learnings from previous PRs, here are my suggestions for enhancing AGENTS.md: Suggested Additions1. Coding Philosophy & Decision-Making SectionAdd a new section after "Architecture & Patterns" to capture project-specific principles: ## Coding Philosophy & Trade-offs
### Simplicity First
When implementing features, **favor simplicity over handling rare edge cases** if the additional complexity creates significant overhead. It's better to have a simple, maintainable solution that covers 95% of use cases than a complex one attempting to cover 100%.
**Example scenarios:**
- URL parsing utilities don't need to handle protocol-relative URLs unless there's a concrete use case
- Input validation can focus on common cases rather than exotic inputs
- Helper functions should solve the immediate problem, not anticipate every possible future need
**When to add complexity:**
- Security-critical paths (always handle edge cases)
- User-facing features with clear requirements
- When the edge case is likely to occur in production
- When technical debt would be higher than upfront complexity
### Encapsulation Over Convenience
Maintain strong module boundaries even when it makes testing slightly harder.
**Key principles:**
- **Don't export internal constants/utilities just for testing purposes**
- Test the public API and behavior, not implementation details
- If something needs testing, consider whether it should be public
- Use integration tests for complex internal logic rather than exposing internals
**Testing approach:**
```javascript
// ❌ Don't export INTERNAL_CONSTANT just to test it
export const INTERNAL_CONSTANT = 'value'
// ✅ Test the behavior through public API
export function publicFunction() {
const INTERNAL_CONSTANT = 'value'
// ... use it
}3. Add "When to Push Back on Requirements" Section## When to Push Back on Requirements
As an AI coding agent, it's important to recognize when a requested change might introduce unnecessary complexity:
**Consider pushing back or discussing alternatives when:**
- A feature request adds significant complexity for minimal benefit
- Edge case handling would make the code much harder to maintain
- The requirement breaks encapsulation (e.g., "expose this for testing")
- The proposed solution violates existing patterns without clear justification
**How to push back constructively:**
1. Acknowledge the concern/requirement
2. Explain the complexity/maintenance cost
3. Suggest a simpler alternative that covers the main use case
4. Let the maintainer make the final decision4. Expand "Common Pitfalls" SectionAdd to existing pitfalls: - **Don't over-engineer solutions** - Implement what's needed now, not what might be needed later
- **Don't expose internals for testing** - Maintain encapsulation even when it makes testing slightly harder
- **Don't handle every edge case** - Focus on common scenarios unless dealing with security-critical code
- **Don't use `faker.string.uuid()`** - Use `faker.datatype.uuid()` instead (version compatibility)These additions would help AI agents better align with your project's philosophy of pragmatic simplicity and strong encapsulation, based on the patterns I've learned from previous interactions. Would you like me to format these as a complete section that you can paste directly into AGENTS.md? ✏️ Learnings added
🧠 Learnings used |
See https://agents.md for detailed information.
Summary by CodeRabbit
✏️ Tip: You can customize this high-level summary in your review settings.